From 316866db57ef5cd883a5eee2dd780e04cc3f133d Mon Sep 17 00:00:00 2001 From: Thibault Lestang Date: Mon, 11 May 2020 08:12:45 +0100 Subject: [PATCH 1/7] Add quickstart section to doc #987 --- docs/index.rst | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 1ec6349371..3d2316a6c7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,8 +15,31 @@ documentation* for ``pybamm``. * :ref:`modindex` * :ref:`search` -Contents -======== +Quickstart +========================= +PyBaMM is available on GNU/Linux, MacOS and Windows. + +Using pip +---------- + +.. code:: bash + + pip install pybamm + +Using conda +------------- +PyBaMM is available as a conda package through the conda-forge channel. + +.. code:: bash + + conda install -c conda-forge pybamm + +Optional solvers +----------------- +Some optional features require extra installation steps, :ref:`optional-deps`. + +API documentation +==================== .. module:: pybamm From c211bd61740199a085e4db5849f08c0fa56f52af Mon Sep 17 00:00:00 2001 From: Thibault Lestang Date: Mon, 11 May 2020 08:51:18 +0100 Subject: [PATCH 2/7] Add installation section #987 --- docs/index.rst | 40 ++++--- docs/install/GNU-linux.rst | 211 ++++++++++++++++++++++++++++++++++ docs/install/GNU-linux.rst~ | 209 +++++++++++++++++++++++++++++++++ docs/install/windows-wsl.rst | 109 ++++++++++++++++++ docs/install/windows-wsl.rst~ | 104 +++++++++++++++++ docs/install/windows.rst | 80 +++++++++++++ docs/install/windows.rst~ | 75 ++++++++++++ 7 files changed, 813 insertions(+), 15 deletions(-) create mode 100644 docs/install/GNU-linux.rst create mode 100644 docs/install/GNU-linux.rst~ create mode 100644 docs/install/windows-wsl.rst create mode 100644 docs/install/windows-wsl.rst~ create mode 100644 docs/install/windows.rst create mode 100644 docs/install/windows.rst~ diff --git a/docs/index.rst b/docs/index.rst index 3d2316a6c7..293e75975c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -38,27 +38,37 @@ Optional solvers ----------------- Some optional features require extra installation steps, :ref:`optional-deps`. +Installation +============ + +.. toctree:: + :maxdepth: 1 + + install/GNU-linux + install/windows + install/windows-wsl + API documentation ==================== .. module:: pybamm .. toctree:: - :maxdepth: 2 - - source/expression_tree/index - source/models/index - source/parameters/index - source/geometry/index - source/meshes/index - source/spatial_methods/index - source/solvers/index - source/experiments/index - source/simulation - source/quick_plot - source/util - source/citations - source/parameters_cli + :maxdepth: 2 + + source/expression_tree/index + source/models/index + source/parameters/index + source/geometry/index + source/meshes/index + source/spatial_methods/index + source/solvers/index + source/experiments/index + source/simulation + source/quick_plot + source/util + source/citations + source/parameters_cli Examples ======== diff --git a/docs/install/GNU-linux.rst b/docs/install/GNU-linux.rst new file mode 100644 index 0000000000..3e8d3e82d6 --- /dev/null +++ b/docs/install/GNU-linux.rst @@ -0,0 +1,211 @@ +GNU-Linux & MacOS +====================== + +.. contents:: + +Prerequisites +--------------- + +To use and/or contribute to PyBaMM, you must have Python 3.6 or 3.7 +installed (note that 3.8 is not yet supported). + +To install Python 3 on Debian-based distribution (Debian, Ubuntu, Linux +mint), open a terminal and run + +.. code:: bash + + sudo apt update + sudo apt install python3 + +On Fedora or CentOS, you can use DNF or Yum. For example + +.. code:: bash + + sudo dnf install python3 + +On Mac OS distributions, you can use ``homebrew``. First `install +``brew`` `__: + +.. code:: bash + + ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" + +then follow instructions in link on adding brew to path, and run + +.. code:: bash + + brew install python3 + +Install PyBaMM +----------------- + +User install +~~~~~~~~~~~~ + +We recommend to install PyBaMM within a virtual environment, in order +not to alter any distribution python files. To create a virtual +environment ``env`` within your current directory type: + +.. code:: bash + + python3 -m venv env + +You can then “activate” the environment using: + +.. code:: bash + + source env/bin/activate + +Now all the calls to pip described below will install PyBaMM and its +dependencies into the environment ``env``. When you are ready to exit +the environment and go back to your original system, just type: + +.. code:: bash + + deactivate + +PyBaMM can be installed via pip: + +.. code:: bash + + pip install pybamm + +PyBaMM’s dependencies (such as ``numpy``, ``scipy``, etc) will be +installed automatically when you install PyBaMM using ``pip``. + +For an introduction to virtual environments, see +(https://realpython.com/python-virtual-environments-a-primer/). + +Optional - scikits.odes solver +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Users can install `scikits.odes `__ in +order to use the wrapped SUNDIALS ODE and DAE +`solvers `__. + +**A pre-requisite** is the installation of a BLAS library (such as +`openblas `__). On Ubuntu/debian + +:: + + sudo apt install libopenblas-dev + +and on Mac OS + +:: + + brew install openblas + +After installing PyBaMM, the following command can be used to +automatically install ``scikits.odes`` and its dependencies + +:: + + $ pybamm_install_odes --install-sundials + +The ``--install-sundials`` option is used to activate automatic +downloads and installation of the sundials library, which is required by +``scikits.odes``. + +Developer install +~~~~~~~~~~~~~~~~~~ + +If you wish to contribute to PyBaMM, you should get the latest version +from the GitHub repository. To do so, you must have Git and graphviz +installed. For instance run + +.. code:: bash + + sudo apt install git graphviz + +on Debian-based distributions, or + +.. code:: bash + + brew install git graphviz + +on Mac OS. + +To install PyBaMM, the first step is to get the code by cloning this +repository + +.. code:: bash + + git clone https://github.com/pybamm-team/PyBaMM.git + cd PyBaMM + +Then, to install PyBaMM as a `developer `__, type + +.. code:: bash + + pip install -e .[dev,docs] + +**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, but +it is unlikely to be installed as you may not have all the dependencies +available. If you wish to install the KLU from the PyBaMM sources, see +`compiling the KLU sparse solver `__. + +To check whether PyBaMM has installed properly, you can run the tests: + +.. code:: bash + + python3 run-tests.py --unit + +Before you start contributing to PyBaMM, please read the `contributing +guidelines `__. + +Uninstall PyBaMM +-------------------- + +PyBaMM can be uninstalled by running + +.. code:: bash + + pip uninstall pybamm + +in your virtual environment. + +Troubleshooting +------------------- + +**Problem:** I’ve made edits to source files in PyBaMM, but these are +not being used when I run my Python script. + +**Solution:** Make sure you have installed PyBaMM using the ``-e`` flag, +i.e. ``pip install -e .``. This sets the installed location of the +source files to your current directory. + +**Problem:** When running ``python run-tests.py --quick``, gives error +``FileNotFoundError: [Errno 2] No such file or directory: 'flake8': 'flake8``. + +**Solution:** make sure you have included the ``[dev,docs]`` flags when +you pip installed PyBaMM, i.e. ``pip install -e .[dev,docs]`` + +**Problem:** Errors when solving model +``ValueError: Integrator name ida does not exsist``, or +``ValueError: Integrator name cvode does not exsist``. + +**Solution:** This could mean that you have not installed +``scikits.odes`` correctly, check the instructions given above and make +sure each command was successful. + +One possibility is that you have not set your ``LD_LIBRARY_PATH`` to +point to the sundials library, type ``echo $LD_LIBRARY_PATH`` and make +sure one of the directories printed out corresponds to where the +sundials libraries are located. + +Another common reason is that you forget to install a BLAS library such +as OpenBLAS before installing sundials. Check the cmake output when you +configured Sundials, it might say: + +:: + + -- A library with BLAS API not found. Please specify library location. + -- LAPACK requires BLAS + +If this is the case, on a Debian or Ubuntu system you can install +OpenBLAS using ``sudo apt-get install libopenblas-dev`` (or +``brew install openblas`` for Mac OS) and then re-install sundials using +the instructions above. diff --git a/docs/install/GNU-linux.rst~ b/docs/install/GNU-linux.rst~ new file mode 100644 index 0000000000..c41f901e12 --- /dev/null +++ b/docs/install/GNU-linux.rst~ @@ -0,0 +1,209 @@ +GNU-Linux +=========== + +Prerequisites +--------------- + +To use and/or contribute to PyBaMM, you must have Python 3.6 or 3.7 +installed (note that 3.8 is not yet supported). + +To install Python 3 on Debian-based distribution (Debian, Ubuntu, Linux +mint), open a terminal and run + +.. code:: bash + + sudo apt update + sudo apt install python3 + +On Fedora or CentOS, you can use DNF or Yum. For example + +.. code:: bash + + sudo dnf install python3 + +On Mac OS distributions, you can use ``homebrew``. First `install +``brew`` `__: + +.. code:: bash + + ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" + +then follow instructions in link on adding brew to path, and run + +.. code:: bash + + brew install python3 + +Install PyBaMM +----------------- + +User install +~~~~~~~~~~~~ + +We recommend to install PyBaMM within a virtual environment, in order +not to alter any distribution python files. To create a virtual +environment ``env`` within your current directory type: + +.. code:: bash + + python3 -m venv env + +You can then “activate” the environment using: + +.. code:: bash + + source env/bin/activate + +Now all the calls to pip described below will install PyBaMM and its +dependencies into the environment ``env``. When you are ready to exit +the environment and go back to your original system, just type: + +.. code:: bash + + deactivate + +PyBaMM can be installed via pip: + +.. code:: bash + + pip install pybamm + +PyBaMM’s dependencies (such as ``numpy``, ``scipy``, etc) will be +installed automatically when you install PyBaMM using ``pip``. + +For an introduction to virtual environments, see +(https://realpython.com/python-virtual-environments-a-primer/). + +Optional - scikits.odes solver +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Users can install `scikits.odes `__ in +order to use the wrapped SUNDIALS ODE and DAE +`solvers `__. + +**A pre-requisite** is the installation of a BLAS library (such as +`openblas `__). On Ubuntu/debian + +:: + + sudo apt install libopenblas-dev + +and on Mac OS + +:: + + brew install openblas + +After installing PyBaMM, the following command can be used to +automatically install ``scikits.odes`` and its dependencies + +:: + + $ pybamm_install_odes --install-sundials + +The ``--install-sundials`` option is used to activate automatic +downloads and installation of the sundials library, which is required by +``scikits.odes``. + +Developer install +~~~~~~~~~~~~~~~~~~ + +If you wish to contribute to PyBaMM, you should get the latest version +from the GitHub repository. To do so, you must have Git and graphviz +installed. For instance run + +.. code:: bash + + sudo apt install git graphviz + +on Debian-based distributions, or + +.. code:: bash + + brew install git graphviz + +on Mac OS. + +To install PyBaMM, the first step is to get the code by cloning this +repository + +.. code:: bash + + git clone https://github.com/pybamm-team/PyBaMM.git + cd PyBaMM + +Then, to install PyBaMM as a `developer `__, type + +.. code:: bash + + pip install -e .[dev,docs] + +**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, but +it is unlikely to be installed as you may not have all the dependencies +available. If you wish to install the KLU from the PyBaMM sources, see +`compiling the KLU sparse solver `__. + +To check whether PyBaMM has installed properly, you can run the tests: + +.. code:: bash + + python3 run-tests.py --unit + +Before you start contributing to PyBaMM, please read the `contributing +guidelines `__. + +Uninstall PyBaMM +-------------------- + +PyBaMM can be uninstalled by running + +.. code:: bash + + pip uninstall pybamm + +in your virtual environment. + +Troubleshooting +------------------- + +**Problem:** I’ve made edits to source files in PyBaMM, but these are +not being used when I run my Python script. + +**Solution:** Make sure you have installed PyBaMM using the ``-e`` flag, +i.e. ``pip install -e .``. This sets the installed location of the +source files to your current directory. + +**Problem:** When running ``python run-tests.py --quick``, gives error +``FileNotFoundError: [Errno 2] No such file or directory: 'flake8': 'flake8``. + +**Solution:** make sure you have included the ``[dev,docs]`` flags when +you pip installed PyBaMM, i.e. ``pip install -e .[dev,docs]`` + +**Problem:** Errors when solving model +``ValueError: Integrator name ida does not exsist``, or +``ValueError: Integrator name cvode does not exsist``. + +**Solution:** This could mean that you have not installed +``scikits.odes`` correctly, check the instructions given above and make +sure each command was successful. + +One possibility is that you have not set your ``LD_LIBRARY_PATH`` to +point to the sundials library, type ``echo $LD_LIBRARY_PATH`` and make +sure one of the directories printed out corresponds to where the +sundials libraries are located. + +Another common reason is that you forget to install a BLAS library such +as OpenBLAS before installing sundials. Check the cmake output when you +configured Sundials, it might say: + +:: + + -- A library with BLAS API not found. Please specify library location. + -- LAPACK requires BLAS + +If this is the case, on a Debian or Ubuntu system you can install +OpenBLAS using ``sudo apt-get install libopenblas-dev`` (or +``brew install openblas`` for Mac OS) and then re-install sundials using +the instructions above. diff --git a/docs/install/windows-wsl.rst b/docs/install/windows-wsl.rst new file mode 100644 index 0000000000..ecad05bf9b --- /dev/null +++ b/docs/install/windows-wsl.rst @@ -0,0 +1,109 @@ +Windows Subsystem for Linux (WSL) +====================================== + +We recommend the use of Windows Subsystem for Linux (WSL) to install +PyBaMM, see the instructions below to get PyBaMM working using Windows, +WSL and VSCode. + +.. contents:: + +Install WSL +----------- + +Follow the instructions from Microsoft +`here `__. +When given the option, choose the Ubuntu 18.04 LTS distribution to +install. Don’t forget to initialise the Ubuntu installation using the +instructions given +`here `__. + +Install PyBaMM +-------------- + +Open a terminal window in your installed Ubuntu distribution by +selecting “Ubuntu” from the start menu. This should give you a bash +prompt in your home directory. + +To download the PyBaMM source code, you first need to install git, which +you can do by typing + +.. code:: bash + + sudo apt install git-core + +For easier integration with WSL, we recommend that you install PyBaMM in +your *Windows* Documents folder, for example by first navigating to + +.. code:: bash + + $ cd /mnt/c/Users/USER_NAME/Documents + +where USER_NAME is your username. Exact path to Windows documents may +vary. Now use git to clone the PyBaMM repository: + +.. code:: bash + + 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: + +.. code:: bash + + cd PyBaMM + +If you are unfamiliar with the linux command line, you might find it +useful to work through this +`tutorial `__ +provided by Ubuntu. + +Now head over and follow the installation instructions for PyBaMM for +linux `here `__. + +Use Visual Studio Code to run PyBaMM +------------------------------------ + +You will probably want to use a native Windows IDE such as Visual Studio +Code or the full Microsoft Visual Studio IDE. Both of these packages can +connect to WSL so that you can write python code in a native windows +environment, while at the same time using WSL to run the code using your +installed Ubuntu distribution. The following instructions assume that +you are using Visual Studio Code. + +First, setup VSCode to run within the ``PyBaMM`` directory that you +created above, using the instructions provided +`here `__. + +Once you have opened the ``PyBaMM`` folder in vscode, use the +``Extensions`` panel to install the ``Python`` extension from Microsoft. +Note that extensions are either installed on the Windows (Local) or on +in WSL (WSL:Ubuntu), so even if you have used VSCode previously with the +Python extension, you probably haven’t installed it in WSL. Make sure to +reload after installing the Python extension so that it is available. + +If you have installed PyBaMM into the virtual environment ``env`` as in +the PyBaMM linux install guide, then VSCode should automatically start +using this environment and you should see something similar to “Python +3.6.8 64-bit (‘env’: venv)” in the bottom bar. + +To test that vscode can run a PyBaMM script, navigate to the +``examples/scripts`` folder and right click on the ``create-model.py`` +script. Select “Run current file in Python Interactive Window”. This +should run the script, which sets up and solves a model of SEI thickness +using PyBaMM. You should see a plot of SEI thickness versus time pop up +in the interactive window. + +The Python Interactive Window in VSCode can be used to view plots, but +is restricted in functionality and cannot, for example, launch separate +windows to show plot. To setup an xserver on windows and use this to +launch windows for plotting, follow these instructions: + +1. Install VcXsrv from + `here `__. +2. Set the display port in the WSL command-line: + ``echo "export DISPLAY=localhost:0.0" >> ~/.bashrc`` +3. Install python3-tk in WSL: ``sudo apt-get install python3-tk`` +4. Set the matplotlib backend to TKAgg in WSL: + ``echo "backend : TKAgg" >> ~/.config/matplotlib/matplotlibrc`` +5. Before running the code, just launch XLaunch (with the default + settings) from within Windows. Then the code works as usual. diff --git a/docs/install/windows-wsl.rst~ b/docs/install/windows-wsl.rst~ new file mode 100644 index 0000000000..541e00ef4c --- /dev/null +++ b/docs/install/windows-wsl.rst~ @@ -0,0 +1,104 @@ +We recommend the use of Windows Subsystem for Linux (WSL) to install +PyBaMM, see the instructions below to get PyBaMM working using Windows, +WSL and VSCode. + +Install WSL +----------- + +Follow the instructions from Microsoft +`here `__. +When given the option, choose the Ubuntu 18.04 LTS distribution to +install. Don’t forget to initialise the Ubuntu installation using the +instructions given +`here `__. + +Install PyBaMM +-------------- + +Open a terminal window in your installed Ubuntu distribution by +selecting “Ubuntu” from the start menu. This should give you a bash +prompt in your home directory. + +To download the PyBaMM source code, you first need to install git, which +you can do by typing + +.. code:: bash + + sudo apt install git-core + +For easier integration with WSL, we recommend that you install PyBaMM in +your *Windows* Documents folder, for example by first navigating to + +.. code:: bash + + $ cd /mnt/c/Users/USER_NAME/Documents + +where USER_NAME is your username. Exact path to Windows documents may +vary. Now use git to clone the PyBaMM repository: + +.. code:: bash + + 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: + +.. code:: bash + + cd PyBaMM + +If you are unfamiliar with the linux command line, you might find it +useful to work through this +`tutorial `__ +provided by Ubuntu. + +Now head over and follow the installation instructions for PyBaMM for +linux `here `__. + +Use Visual Studio Code to run PyBaMM +------------------------------------ + +You will probably want to use a native Windows IDE such as Visual Studio +Code or the full Microsoft Visual Studio IDE. Both of these packages can +connect to WSL so that you can write python code in a native windows +environment, while at the same time using WSL to run the code using your +installed Ubuntu distribution. The following instructions assume that +you are using Visual Studio Code. + +First, setup VSCode to run within the ``PyBaMM`` directory that you +created above, using the instructions provided +`here `__. + +Once you have opened the ``PyBaMM`` folder in vscode, use the +``Extensions`` panel to install the ``Python`` extension from Microsoft. +Note that extensions are either installed on the Windows (Local) or on +in WSL (WSL:Ubuntu), so even if you have used VSCode previously with the +Python extension, you probably haven’t installed it in WSL. Make sure to +reload after installing the Python extension so that it is available. + +If you have installed PyBaMM into the virtual environment ``env`` as in +the PyBaMM linux install guide, then VSCode should automatically start +using this environment and you should see something similar to “Python +3.6.8 64-bit (‘env’: venv)” in the bottom bar. + +To test that vscode can run a PyBaMM script, navigate to the +``examples/scripts`` folder and right click on the ``create-model.py`` +script. Select “Run current file in Python Interactive Window”. This +should run the script, which sets up and solves a model of SEI thickness +using PyBaMM. You should see a plot of SEI thickness versus time pop up +in the interactive window. + +The Python Interactive Window in VSCode can be used to view plots, but +is restricted in functionality and cannot, for example, launch separate +windows to show plot. To setup an xserver on windows and use this to +launch windows for plotting, follow these instructions: + +1. Install VcXsrv from + `here `__. +2. Set the display port in the WSL command-line: + ``echo "export DISPLAY=localhost:0.0" >> ~/.bashrc`` +3. Install python3-tk in WSL: ``sudo apt-get install python3-tk`` +4. Set the matplotlib backend to TKAgg in WSL: + ``echo "backend : TKAgg" >> ~/.config/matplotlib/matplotlibrc`` +5. Before running the code, just launch XLaunch (with the default + settings) from within Windows. Then the code works as usual. diff --git a/docs/install/windows.rst b/docs/install/windows.rst new file mode 100644 index 0000000000..1e4f8dea0d --- /dev/null +++ b/docs/install/windows.rst @@ -0,0 +1,80 @@ +Windows +========== + +.. contents:: + +Prerequisites +------------- + +To use and/or contribute to PyBaMM, you must have Python 3.6 or 3.7 +installed (note that 3.8 is not yet supported). + +To install Python 3 download the installation files from `Python’s +website `__. Make sure to +tick the box on ``Add Python 3.X to PATH``. For more detailed +instructions please see the `official Python on Windows +guide `__. + +Install PyBaMM +-------------- + +User install +~~~~~~~~~~~~ + +Launch the Command Prompt and go to the directory where you want to +install PyBaMM. You can find a reminder of how to navigate the terminal +`here `__. + +We recommend to install PyBaMM within a virtual environment, in order +not to alter any distribution python files. + +To create a virtual environment ``env`` within your current directory +type: + +.. code:: bash + + python -m venv env + +You can then “activate” the environment using: + +.. code:: bash + + env\Scripts\activate.bat + +Now all the calls to pip described below will install PyBaMM and its +dependencies into the environment ``env``. When you are ready to exit +the environment and go back to your original system, just type: + +.. code:: bash + + deactivate + +PyBaMM can be installed via pip: + +.. code:: bash + + pip install pybamm + +PyBaMM’s dependencies (such as ``numpy``, ``scipy``, etc) will be +installed automatically when you install PyBaMM using ``pip``. + +For an introduction to virtual environments, see +(https://realpython.com/python-virtual-environments-a-primer/). + +Uninstall PyBaMM +---------------- + +PyBaMM can be uninstalled by running + +.. code:: bash + + pip uninstall pybamm + +in your virtual environment. + +Installation using WSL +---------------------- + +If you want to install the optional PyBaMM solvers, you have to use the +Windows Subsystem for Linux (WSL). You can find the installation +instructions `here `__. diff --git a/docs/install/windows.rst~ b/docs/install/windows.rst~ new file mode 100644 index 0000000000..b24de78d4b --- /dev/null +++ b/docs/install/windows.rst~ @@ -0,0 +1,75 @@ +Prerequisites +------------- + +To use and/or contribute to PyBaMM, you must have Python 3.6 or 3.7 +installed (note that 3.8 is not yet supported). + +To install Python 3 download the installation files from `Python’s +website `__. Make sure to +tick the box on ``Add Python 3.X to PATH``. For more detailed +instructions please see the `official Python on Windows +guide `__. + +Install PyBaMM +-------------- + +User install +~~~~~~~~~~~~ + +Launch the Command Prompt and go to the directory where you want to +install PyBaMM. You can find a reminder of how to navigate the terminal +`here `__. + +We recommend to install PyBaMM within a virtual environment, in order +not to alter any distribution python files. + +To create a virtual environment ``env`` within your current directory +type: + +.. code:: bash + + python -m venv env + +You can then “activate” the environment using: + +.. code:: bash + + env\Scripts\activate.bat + +Now all the calls to pip described below will install PyBaMM and its +dependencies into the environment ``env``. When you are ready to exit +the environment and go back to your original system, just type: + +.. code:: bash + + deactivate + +PyBaMM can be installed via pip: + +.. code:: bash + + pip install pybamm + +PyBaMM’s dependencies (such as ``numpy``, ``scipy``, etc) will be +installed automatically when you install PyBaMM using ``pip``. + +For an introduction to virtual environments, see +(https://realpython.com/python-virtual-environments-a-primer/). + +Uninstall PyBaMM +---------------- + +PyBaMM can be uninstalled by running + +.. code:: bash + + pip uninstall pybamm + +in your virtual environment. + +Installation using WSL +---------------------- + +If you want to install the optional PyBaMM solvers, you have to use the +Windows Subsystem for Linux (WSL). You can find the installation +instructions `here `__. From b27b9157de574cb3b36b536604821ce45a091f3b Mon Sep 17 00:00:00 2001 From: Thibault Lestang Date: Mon, 11 May 2020 08:52:17 +0100 Subject: [PATCH 3/7] Remove autosave files --- docs/install/GNU-linux.rst~ | 209 ---------------------------------- docs/install/windows-wsl.rst~ | 104 ----------------- docs/install/windows.rst~ | 75 ------------ 3 files changed, 388 deletions(-) delete mode 100644 docs/install/GNU-linux.rst~ delete mode 100644 docs/install/windows-wsl.rst~ delete mode 100644 docs/install/windows.rst~ diff --git a/docs/install/GNU-linux.rst~ b/docs/install/GNU-linux.rst~ deleted file mode 100644 index c41f901e12..0000000000 --- a/docs/install/GNU-linux.rst~ +++ /dev/null @@ -1,209 +0,0 @@ -GNU-Linux -=========== - -Prerequisites ---------------- - -To use and/or contribute to PyBaMM, you must have Python 3.6 or 3.7 -installed (note that 3.8 is not yet supported). - -To install Python 3 on Debian-based distribution (Debian, Ubuntu, Linux -mint), open a terminal and run - -.. code:: bash - - sudo apt update - sudo apt install python3 - -On Fedora or CentOS, you can use DNF or Yum. For example - -.. code:: bash - - sudo dnf install python3 - -On Mac OS distributions, you can use ``homebrew``. First `install -``brew`` `__: - -.. code:: bash - - ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" - -then follow instructions in link on adding brew to path, and run - -.. code:: bash - - brew install python3 - -Install PyBaMM ------------------ - -User install -~~~~~~~~~~~~ - -We recommend to install PyBaMM within a virtual environment, in order -not to alter any distribution python files. To create a virtual -environment ``env`` within your current directory type: - -.. code:: bash - - python3 -m venv env - -You can then “activate” the environment using: - -.. code:: bash - - source env/bin/activate - -Now all the calls to pip described below will install PyBaMM and its -dependencies into the environment ``env``. When you are ready to exit -the environment and go back to your original system, just type: - -.. code:: bash - - deactivate - -PyBaMM can be installed via pip: - -.. code:: bash - - pip install pybamm - -PyBaMM’s dependencies (such as ``numpy``, ``scipy``, etc) will be -installed automatically when you install PyBaMM using ``pip``. - -For an introduction to virtual environments, see -(https://realpython.com/python-virtual-environments-a-primer/). - -Optional - scikits.odes solver -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Users can install `scikits.odes `__ in -order to use the wrapped SUNDIALS ODE and DAE -`solvers `__. - -**A pre-requisite** is the installation of a BLAS library (such as -`openblas `__). On Ubuntu/debian - -:: - - sudo apt install libopenblas-dev - -and on Mac OS - -:: - - brew install openblas - -After installing PyBaMM, the following command can be used to -automatically install ``scikits.odes`` and its dependencies - -:: - - $ pybamm_install_odes --install-sundials - -The ``--install-sundials`` option is used to activate automatic -downloads and installation of the sundials library, which is required by -``scikits.odes``. - -Developer install -~~~~~~~~~~~~~~~~~~ - -If you wish to contribute to PyBaMM, you should get the latest version -from the GitHub repository. To do so, you must have Git and graphviz -installed. For instance run - -.. code:: bash - - sudo apt install git graphviz - -on Debian-based distributions, or - -.. code:: bash - - brew install git graphviz - -on Mac OS. - -To install PyBaMM, the first step is to get the code by cloning this -repository - -.. code:: bash - - git clone https://github.com/pybamm-team/PyBaMM.git - cd PyBaMM - -Then, to install PyBaMM as a `developer `__, type - -.. code:: bash - - pip install -e .[dev,docs] - -**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, but -it is unlikely to be installed as you may not have all the dependencies -available. If you wish to install the KLU from the PyBaMM sources, see -`compiling the KLU sparse solver `__. - -To check whether PyBaMM has installed properly, you can run the tests: - -.. code:: bash - - python3 run-tests.py --unit - -Before you start contributing to PyBaMM, please read the `contributing -guidelines `__. - -Uninstall PyBaMM --------------------- - -PyBaMM can be uninstalled by running - -.. code:: bash - - pip uninstall pybamm - -in your virtual environment. - -Troubleshooting -------------------- - -**Problem:** I’ve made edits to source files in PyBaMM, but these are -not being used when I run my Python script. - -**Solution:** Make sure you have installed PyBaMM using the ``-e`` flag, -i.e. ``pip install -e .``. This sets the installed location of the -source files to your current directory. - -**Problem:** When running ``python run-tests.py --quick``, gives error -``FileNotFoundError: [Errno 2] No such file or directory: 'flake8': 'flake8``. - -**Solution:** make sure you have included the ``[dev,docs]`` flags when -you pip installed PyBaMM, i.e. ``pip install -e .[dev,docs]`` - -**Problem:** Errors when solving model -``ValueError: Integrator name ida does not exsist``, or -``ValueError: Integrator name cvode does not exsist``. - -**Solution:** This could mean that you have not installed -``scikits.odes`` correctly, check the instructions given above and make -sure each command was successful. - -One possibility is that you have not set your ``LD_LIBRARY_PATH`` to -point to the sundials library, type ``echo $LD_LIBRARY_PATH`` and make -sure one of the directories printed out corresponds to where the -sundials libraries are located. - -Another common reason is that you forget to install a BLAS library such -as OpenBLAS before installing sundials. Check the cmake output when you -configured Sundials, it might say: - -:: - - -- A library with BLAS API not found. Please specify library location. - -- LAPACK requires BLAS - -If this is the case, on a Debian or Ubuntu system you can install -OpenBLAS using ``sudo apt-get install libopenblas-dev`` (or -``brew install openblas`` for Mac OS) and then re-install sundials using -the instructions above. diff --git a/docs/install/windows-wsl.rst~ b/docs/install/windows-wsl.rst~ deleted file mode 100644 index 541e00ef4c..0000000000 --- a/docs/install/windows-wsl.rst~ +++ /dev/null @@ -1,104 +0,0 @@ -We recommend the use of Windows Subsystem for Linux (WSL) to install -PyBaMM, see the instructions below to get PyBaMM working using Windows, -WSL and VSCode. - -Install WSL ------------ - -Follow the instructions from Microsoft -`here `__. -When given the option, choose the Ubuntu 18.04 LTS distribution to -install. Don’t forget to initialise the Ubuntu installation using the -instructions given -`here `__. - -Install PyBaMM --------------- - -Open a terminal window in your installed Ubuntu distribution by -selecting “Ubuntu” from the start menu. This should give you a bash -prompt in your home directory. - -To download the PyBaMM source code, you first need to install git, which -you can do by typing - -.. code:: bash - - sudo apt install git-core - -For easier integration with WSL, we recommend that you install PyBaMM in -your *Windows* Documents folder, for example by first navigating to - -.. code:: bash - - $ cd /mnt/c/Users/USER_NAME/Documents - -where USER_NAME is your username. Exact path to Windows documents may -vary. Now use git to clone the PyBaMM repository: - -.. code:: bash - - 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: - -.. code:: bash - - cd PyBaMM - -If you are unfamiliar with the linux command line, you might find it -useful to work through this -`tutorial `__ -provided by Ubuntu. - -Now head over and follow the installation instructions for PyBaMM for -linux `here `__. - -Use Visual Studio Code to run PyBaMM ------------------------------------- - -You will probably want to use a native Windows IDE such as Visual Studio -Code or the full Microsoft Visual Studio IDE. Both of these packages can -connect to WSL so that you can write python code in a native windows -environment, while at the same time using WSL to run the code using your -installed Ubuntu distribution. The following instructions assume that -you are using Visual Studio Code. - -First, setup VSCode to run within the ``PyBaMM`` directory that you -created above, using the instructions provided -`here `__. - -Once you have opened the ``PyBaMM`` folder in vscode, use the -``Extensions`` panel to install the ``Python`` extension from Microsoft. -Note that extensions are either installed on the Windows (Local) or on -in WSL (WSL:Ubuntu), so even if you have used VSCode previously with the -Python extension, you probably haven’t installed it in WSL. Make sure to -reload after installing the Python extension so that it is available. - -If you have installed PyBaMM into the virtual environment ``env`` as in -the PyBaMM linux install guide, then VSCode should automatically start -using this environment and you should see something similar to “Python -3.6.8 64-bit (‘env’: venv)” in the bottom bar. - -To test that vscode can run a PyBaMM script, navigate to the -``examples/scripts`` folder and right click on the ``create-model.py`` -script. Select “Run current file in Python Interactive Window”. This -should run the script, which sets up and solves a model of SEI thickness -using PyBaMM. You should see a plot of SEI thickness versus time pop up -in the interactive window. - -The Python Interactive Window in VSCode can be used to view plots, but -is restricted in functionality and cannot, for example, launch separate -windows to show plot. To setup an xserver on windows and use this to -launch windows for plotting, follow these instructions: - -1. Install VcXsrv from - `here `__. -2. Set the display port in the WSL command-line: - ``echo "export DISPLAY=localhost:0.0" >> ~/.bashrc`` -3. Install python3-tk in WSL: ``sudo apt-get install python3-tk`` -4. Set the matplotlib backend to TKAgg in WSL: - ``echo "backend : TKAgg" >> ~/.config/matplotlib/matplotlibrc`` -5. Before running the code, just launch XLaunch (with the default - settings) from within Windows. Then the code works as usual. diff --git a/docs/install/windows.rst~ b/docs/install/windows.rst~ deleted file mode 100644 index b24de78d4b..0000000000 --- a/docs/install/windows.rst~ +++ /dev/null @@ -1,75 +0,0 @@ -Prerequisites -------------- - -To use and/or contribute to PyBaMM, you must have Python 3.6 or 3.7 -installed (note that 3.8 is not yet supported). - -To install Python 3 download the installation files from `Python’s -website `__. Make sure to -tick the box on ``Add Python 3.X to PATH``. For more detailed -instructions please see the `official Python on Windows -guide `__. - -Install PyBaMM --------------- - -User install -~~~~~~~~~~~~ - -Launch the Command Prompt and go to the directory where you want to -install PyBaMM. You can find a reminder of how to navigate the terminal -`here `__. - -We recommend to install PyBaMM within a virtual environment, in order -not to alter any distribution python files. - -To create a virtual environment ``env`` within your current directory -type: - -.. code:: bash - - python -m venv env - -You can then “activate” the environment using: - -.. code:: bash - - env\Scripts\activate.bat - -Now all the calls to pip described below will install PyBaMM and its -dependencies into the environment ``env``. When you are ready to exit -the environment and go back to your original system, just type: - -.. code:: bash - - deactivate - -PyBaMM can be installed via pip: - -.. code:: bash - - pip install pybamm - -PyBaMM’s dependencies (such as ``numpy``, ``scipy``, etc) will be -installed automatically when you install PyBaMM using ``pip``. - -For an introduction to virtual environments, see -(https://realpython.com/python-virtual-environments-a-primer/). - -Uninstall PyBaMM ----------------- - -PyBaMM can be uninstalled by running - -.. code:: bash - - pip uninstall pybamm - -in your virtual environment. - -Installation using WSL ----------------------- - -If you want to install the optional PyBaMM solvers, you have to use the -Windows Subsystem for Linux (WSL). You can find the installation -instructions `here `__. From 988a61ef7ed9d9272deee676b3bec3093372e5f4 Mon Sep 17 00:00:00 2001 From: Thibault Lestang Date: Mon, 11 May 2020 09:08:22 +0100 Subject: [PATCH 4/7] Add link to scikits.odes solver instructions in quickstart section #987 --- docs/index.rst | 2 +- docs/install/GNU-linux.rst | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 293e75975c..746b559764 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -36,7 +36,7 @@ PyBaMM is available as a conda package through the conda-forge channel. Optional solvers ----------------- -Some optional features require extra installation steps, :ref:`optional-deps`. +On GNU/Linux and MacOS, an optional `scikits.odes `_ -based solver is available, see :ref:`scikits.odes-label`. Installation ============ diff --git a/docs/install/GNU-linux.rst b/docs/install/GNU-linux.rst index 3e8d3e82d6..74db315fec 100644 --- a/docs/install/GNU-linux.rst +++ b/docs/install/GNU-linux.rst @@ -76,6 +76,8 @@ installed automatically when you install PyBaMM using ``pip``. For an introduction to virtual environments, see (https://realpython.com/python-virtual-environments-a-primer/). +.. _scikits.odes-label: + Optional - scikits.odes solver ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From f4477329e1e926c173a898c58ad63bb39d38c977 Mon Sep 17 00:00:00 2001 From: Thibault Lestang Date: Mon, 11 May 2020 09:28:01 +0100 Subject: [PATCH 5/7] Add instructions on how to compile KLU solver #987 --- docs/index.rst | 1 + docs/install/GNU-linux.rst | 2 +- docs/install/install-klu.rst | 247 +++++++++++++++++++++++++++++++++++ 3 files changed, 249 insertions(+), 1 deletion(-) create mode 100644 docs/install/install-klu.rst diff --git a/docs/index.rst b/docs/index.rst index 746b559764..0ec015f49d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -47,6 +47,7 @@ Installation install/GNU-linux install/windows install/windows-wsl + For developers: compiling the KLU solver API documentation ==================== diff --git a/docs/install/GNU-linux.rst b/docs/install/GNU-linux.rst index 74db315fec..32a7ae9f57 100644 --- a/docs/install/GNU-linux.rst +++ b/docs/install/GNU-linux.rst @@ -147,7 +147,7 @@ Then, to install PyBaMM as a `developer `__, type offers a direct interface to the sparse KLU solver within Sundials, but it is unlikely to be installed as you may not have all the dependencies available. If you wish to install the KLU from the PyBaMM sources, see -`compiling the KLU sparse solver `__. +:doc:`the instructions for compiling the KLU sparse solver `. To check whether PyBaMM has installed properly, you can run the tests: diff --git a/docs/install/install-klu.rst b/docs/install/install-klu.rst new file mode 100644 index 0000000000..19a6615e9d --- /dev/null +++ b/docs/install/install-klu.rst @@ -0,0 +1,247 @@ +PyBaMM developer install - The KLU sparse solver +================================================ + +If you wish to try a different DAE solver, PyBaMM currently offers a +direct interface to the sparse KLU solver within Sundials. This solver +comes as a C++ python extension module. Therefore, when installing +PyBaMM from source (e.g. from the GitHub repository), the KLU sparse +solver module must be compiled. Running ``pip install .`` or +``python setup.py install`` in the PyBaMM directory will result in a +attempt to compile the KLU module. + +Note that if CMake of pybind11 are not found (see below), the +installation of PyBaMM will carry on, however skipping the compilation +of the ``idaklu`` module. This allows developers that are not interested +in the KLU module to install PyBaMM from source without having to +install the required dependencies. + +To build the KLU solver, the following dependencies are required: + +- A C++ compiler (e.g. ``g++``) +- A Fortran compiler (e.g. ``gfortran``) +- The python 3 header files +- `CMake `__ +- A BLAS implementation (e.g. `openblas `__) +- `pybind11 `__ +- `sundials `__ +- `SuiteSparse `__ + +The first four should be available through your favourite package +manager. On Debian-based GNU/Linux distributions: + +.. code:: bash + + apt update + apt install python3-dev gcc gfortran cmake libopenblas-dev + +pybind11 +-------- + +The pybind11 source directory should be located in the PyBaMM project +directory at the time of compilation. Simply clone the GitHub +repository, for example: + +.. code:: bash + + # In the PyBaMM project dir (next to setup.py) + git clone https://github.com/pybind/pybind11.git + +SuiteSparse and sundials +------------------------ + +Method 1 - Using the convenience script +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The PyBaMM repository contains a script +``scripts/setup_KLU_module_build.py`` that automatically downloads, +extracts, compiles and installs the two libraries. + +First install the Python ``wget`` module + +:: + + pip install wget + +Then execute the script + +:: + + # In the PyBaMM project dir (next to setup.py) + python scripts/setup_KLU_module_build.py + +The above will install the required component of SuiteSparse and +Sundials in your home directory under ``~/.local/``. Note that you can +provide the option ``--install-dir=`` to install both +libraries to an alternative location. If ```` is not +absolute, it will be interpreted as relative to the PyBaMM project +directory. + +Finally, reactivate your virtual environment by running + +:: + + source $(VIRTUAL_ENV)/bin/activate + +Alternatively, you update the ``LD_LIBRARY_PATH`` environment variable +as follows + +:: + + export LD_LIBRARY_PATH=$(HOME)/.local:$LD_LIBRARY_PATH + +The above export statement will be ran automatically the next time you +activate you python virtual environment. + +If did not run the convenience script inside a python virtual +environment, execute you bash config file + +:: + + source ~/.bashrc + +(or start a new shell). + +Build files are located inside the PyBaMM project directory under +``KLU_module_deps/``. Feel free to remove this directory once everything +is installed correctly. + +Method 2 - Compiling Sundials (advanced) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +SuiteSparse +^^^^^^^^^^^ + +On most current linux distributions and macOS, a recent enough version +of the suitesparse source package is available through the package +manager. For instance on Fedora + +:: + + yum install libsuitesparse-dev + +Sundials +^^^^^^^^ + +The PyBaMM KLU solver requires Sundials >= 4.0. Because most Linux +distribution provide older versions through their respective package +manager, it is recommended to build and install Sundials manually. + +First, download and extract the sundials 5.0.0 source + +:: + + wget https://computing.llnl.gov/projects/sundials/download/sundials-5.0.0.tar.gz . + tar -xvf sundials-5.0.0.tar.gz + +Then, create a temporary build directory and navigate into it + +:: + + mkdir build_sundials + cd build_sundials + +You can now configure the build, by running + +:: + + cmake -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\ + -DKLU_ENABLE=ON\ + -DKLU_INCLUDE_DIR=path/to/suitesparse/headers\ + -DKLU_LIBRARY_DIR=path/to/suitesparse/libraries\ + ../sundials-5.0.0 + +Be careful set the two variables ``KLU_INCLUDE_DIR`` and +``KLU_LIBRARY_DIR`` to the correct installation location of the +SuiteSparse libary on your system. If you installed SuiteSparse through +your package manager, this is likely to be something similar to: + +:: + + -DKLU_INCLUDE_DIR=/usr/include/suitesparse\ + -DKLU_LIBRARY_DIR=/usr/lib/x86_64-linux-gnu\ + +By default, Sundials will be installed on your system under +``/usr/local`` (this varies depending on the distribution). Should you +wish to install sundials in a specific location, set the following +variable + +:: + + -DCMAKE_INSTALL_PREFIX=install/location\ + +Finally, build the library: + +:: + + make install + +You may be asked to run this command as a super-user, depending on the +installation location. + +Alternative installation location +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, it is assumed that the SuiteSparse and Sundials libraries +are installed in your home directory under ``~/.local``. If you +installed the libraries to (a) different location(s), you must set the +options ``suitesparse-root`` or/and ``sundials-root`` when installing +PyBaMM. Examples: + +:: + + python setup.py install --suitesparse-root=path/to/suitesparse + +or + +:: + + pip install . --install-option="--sundials-root=path/to/sundials" + +(re)Install PyBaMM to build the KLU solver +------------------------------------------ + +If the above dependencies are correctly installed, any of the following +commands will install PyBaMM with the ``idaklu`` solver module: + +:: + + pip install . + pip install -e . + python setup.py install + python setup.py develop + ... + +Note that it doesn’t matter if pybamm is already installed. The above +commands will update your exisitng installation by adding the ``idaklu`` +module. + +Check that the solver is correctly installed +-------------------------------------------- + +If you install PyBaMM in `editable +mode `__ +using the ``-e`` pip switch or if you use the +``python setup.py install`` command, a log file will be located in the +project directory (next to the ``setup.py`` file). + +:: + + cat setup.log + 020-03-24 11:33:50,645 - PyBaMM setup - INFO - Starting PyBaMM setup + 2020-03-24 11:33:50,653 - PyBaMM setup - INFO - Not running on windows + 2020-03-24 11:33:50,654 - PyBaMM setup - INFO - Could not find CMake. Skipping compilation of KLU module. + 2020-03-24 11:33:50,655 - PyBaMM setup - INFO - Could not find pybind11 directory (/io/pybind11). Skipping compilation of KLU module. + +If the KLU sparse solver is correctly installed, then the following +command should return ``True``. + +:: + + $ python -c "import pybamm; print(pybamm.have_idaklu())" From d6542933c3fee6bbd8b44aec9caabc3074921b91 Mon Sep 17 00:00:00 2001 From: Thibault Lestang Date: Mon, 11 May 2020 09:29:00 +0100 Subject: [PATCH 6/7] Remove installation instructions in git repo #987 --- INSTALL-LINUX-MAC.md | 163 -------------------------------------- INSTALL-WINDOWS-WSL.md | 89 --------------------- INSTALL-WINDOWS.md | 54 ------------- compiling-KLU.md | 173 ----------------------------------------- 4 files changed, 479 deletions(-) delete mode 100644 INSTALL-LINUX-MAC.md delete mode 100644 INSTALL-WINDOWS-WSL.md delete mode 100644 INSTALL-WINDOWS.md delete mode 100644 compiling-KLU.md diff --git a/INSTALL-LINUX-MAC.md b/INSTALL-LINUX-MAC.md deleted file mode 100644 index 7d37ba9c26..0000000000 --- a/INSTALL-LINUX-MAC.md +++ /dev/null @@ -1,163 +0,0 @@ -## Prerequisites - -To use and/or contribute to PyBaMM, you must have Python 3.6 or 3.7 installed (note that 3.8 is not yet supported). - -To install Python 3 on Debian-based distribution (Debian, Ubuntu, Linux mint), open a terminal and run -```bash -sudo apt update -sudo apt install python3 -``` -On Fedora or CentOS, you can use DNF or Yum. For example -```bash -sudo dnf install python3 -``` -On Mac OS distributions, you can use `homebrew`. -First [install `brew`](https://docs.python-guide.org/starting/install3/osx/): - -```bash -ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" -``` - -then follow instructions in link on adding brew to path, and run - -```bash -brew install python3 -``` - -## Install PyBaMM - -### User install -We recommend to install PyBaMM within a virtual environment, in order not -to alter any distribution python files. -To create a virtual environment `env` within your current directory type: - -```bash -python3 -m venv env -``` -You can then "activate" the environment using: - -```bash -source env/bin/activate -``` -Now all the calls to pip described below will install PyBaMM and its dependencies into -the environment `env`. When you are ready to exit the environment and go back to your -original system, just type: - -```bash -deactivate -``` - -PyBaMM can be installed via pip: -```bash -pip install pybamm -``` - -PyBaMM's dependencies (such as `numpy`, `scipy`, etc) will be installed automatically when you install PyBaMM using `pip`. - -For an introduction to virtual environments, see (https://realpython.com/python-virtual-environments-a-primer/). - -#### Optional - scikits.odes solver -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). - -**A pre-requisite** is the installation of a BLAS library (such as [openblas](https://www.openblas.net/)). -On Ubuntu/debian -``` -sudo apt install libopenblas-dev -``` -and on Mac OS -``` -brew install openblas -``` -After installing PyBaMM, the following command can be used to automatically install `scikits.odes` -and its dependencies -``` -$ pybamm_install_odes --install-sundials -``` -The `--install-sundials` option is used to activate automatic downloads and installation of the sundials library, which is required by `scikits.odes`. - -### Developer install - -If you wish to contribute to PyBaMM, you should get the latest version from the GitHub repository. -To do so, you must have Git and graphviz installed. For instance run - -```bash -sudo apt install git graphviz -``` - -on Debian-based distributions, or - -```bash -brew install git graphviz -``` - -on Mac OS. - -To install PyBaMM, the first step is to get the code by cloning this repository - -```bash -git clone https://github.com/pybamm-team/PyBaMM.git -cd PyBaMM -``` -Then, to install PyBaMM as a [developer](CONTRIBUTING.md), type - -```bash -pip install -e .[dev,docs] -``` - -**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, but it is -unlikely to be installed as you may not have all the dependencies available. If you wish to install the KLU from the PyBaMM sources, see [compiling the KLU sparse solver](compiling_KLU.md). - -To check whether PyBaMM has installed properly, you can run the tests: - -```bash -python3 run-tests.py --unit -``` - -Before you start contributing to PyBaMM, please read the [contributing guidelines](CONTRIBUTING.md). - -## Uninstall PyBaMM -PyBaMM can be uninstalled by running -```bash -pip uninstall pybamm -``` -in your virtual environment. - -## Troubleshooting - -**Problem:** I've made edits to source files in PyBaMM, but these are not being used -when I run my Python script. - -**Solution:** Make sure you have installed PyBaMM using the `-e` flag, i.e. `pip install --e .`. This sets the installed location of the source files to your current directory. - -**Problem:** When running `python run-tests.py --quick`, gives error `FileNotFoundError: -[Errno 2] No such file or directory: 'flake8': 'flake8`. - -**Solution:** make sure you have included the `[dev,docs]` flags when you pip installed -PyBaMM, i.e. `pip install -e .[dev,docs]` - -**Problem:** Errors when solving model `ValueError: Integrator name ida does not -exsist`, or `ValueError: Integrator name cvode does not exsist`. - -**Solution:** This could mean that you have not installed `scikits.odes` correctly, -check the instructions given above and make sure each command was successful. - -One possibility is that you have not set your `LD_LIBRARY_PATH` to point to the sundials -library, type `echo $LD_LIBRARY_PATH` and make sure one of the directories printed out -corresponds to where the sundials libraries are located. - -Another common reason is that you forget to install a BLAS library such as OpenBLAS -before installing sundials. Check the cmake output when you configured Sundials, it -might say: - -``` --- A library with BLAS API not found. Please specify library location. --- LAPACK requires BLAS -``` - -If this is the case, on a Debian or Ubuntu system you can install OpenBLAS using `sudo -apt-get install libopenblas-dev` (or `brew install openblas` for Mac OS) and then re-install sundials using the instructions -above. diff --git a/INSTALL-WINDOWS-WSL.md b/INSTALL-WINDOWS-WSL.md deleted file mode 100644 index 608dfd63f8..0000000000 --- a/INSTALL-WINDOWS-WSL.md +++ /dev/null @@ -1,89 +0,0 @@ -We recommend the use of Windows Subsystem for Linux (WSL) to install PyBaMM, see the -instructions below to get PyBaMM working using Windows, WSL and VSCode. - -## Install WSL - -Follow the instructions from Microsoft -[here](https://docs.microsoft.com/en-us/windows/wsl/install-win10). When given the -option, choose the Ubuntu 18.04 LTS distribution to install. Don't forget to initialise -the Ubuntu installation using the instructions given -[here](https://docs.microsoft.com/en-us/windows/wsl/initialize-distro). - -## Install PyBaMM - -Open a terminal window in your installed Ubuntu distribution by selecting "Ubuntu" from -the start menu. This should give you a bash prompt in your home directory. - -To download the PyBaMM source code, you first need to install git, which you can do by -typing - -```bash -sudo apt install git-core -``` - -For easier integration with WSL, we recommend that you install PyBaMM in your *Windows* -Documents folder, for example by first navigating to - -```bash -$ cd /mnt/c/Users/USER_NAME/Documents -``` - -where USER_NAME is your username. Exact path to Windows documents may vary. Now use git to clone the PyBaMM repository: - -```bash -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 -``` - -If you are unfamiliar with the linux command line, you might find it useful to work through this -[tutorial](https://tutorials.ubuntu.com/tutorial/command-line-for-beginners) provided by Ubuntu. - -Now head over and follow the installation instructions for PyBaMM for linux -[here](INSTALL-LINUX-MAC.md). - -## Use Visual Studio Code to run PyBaMM - -You will probably want to use a native Windows IDE such as Visual Studio Code or the -full Microsoft Visual Studio IDE. Both of these packages can connect to WSL so that you -can write python code in a native windows environment, while at the same time using WSL -to run the code using your installed Ubuntu distribution. The following instructions -assume that you are using Visual Studio Code. - -First, setup VSCode to run within the `PyBaMM` directory that you created above, using -the instructions provided [here](https://code.visualstudio.com/docs/remote/wsl). - -Once you have opened the `PyBaMM` folder in vscode, use the `Extensions` panel to -install the `Python` extension from Microsoft. Note that extensions are either installed -on the Windows (Local) or on in WSL (WSL:Ubuntu), so even if you have used VSCode -previously with the Python extension, you probably haven't installed it in WSL. Make -sure to reload after installing the Python extension so that it is available. - -If you have installed PyBaMM into the virtual environment `env` as in the PyBaMM linux -install guide, then VSCode should automatically start using this environment and you -should see something similar to "Python 3.6.8 64-bit ('env': venv)" in the bottom bar. - -To test that vscode can run a PyBaMM script, navigate to the `examples/scripts` folder -and right click on the `create-model.py` script. Select "Run current file in Python -Interactive Window". This should run the script, which sets up and solves a model of SEI -thickness using PyBaMM. You should see a plot of SEI thickness versus time pop up in the -interactive window. - -The Python Interactive Window in VSCode can be used to view plots, but is restricted in -functionality and cannot, for example, launch separate windows to show plot. To setup an -xserver on windows and use this to launch windows for plotting, follow these -instructions: - -1. Install VcXsrv from [here](https://sourceforge.net/projects/vcxsrv/). -1. Set the display port in the WSL command-line: `echo "export DISPLAY=localhost:0.0" >> - ~/.bashrc` -1. Install python3-tk in WSL: `sudo apt-get install python3-tk` -1. Set the matplotlib backend to TKAgg in WSL: `echo "backend : TKAgg" >> - ~/.config/matplotlib/matplotlibrc` -1. Before running the code, just launch XLaunch (with the default settings) from within - Windows. Then the code works as usual. diff --git a/INSTALL-WINDOWS.md b/INSTALL-WINDOWS.md deleted file mode 100644 index 6f69bf72e8..0000000000 --- a/INSTALL-WINDOWS.md +++ /dev/null @@ -1,54 +0,0 @@ -## Prerequisites - -To use and/or contribute to PyBaMM, you must have Python 3.6 or 3.7 installed (note that 3.8 is not yet supported). - -To install Python 3 download the installation files from [Python's website](https://www.python.org/downloads/windows/). Make sure -to tick the box on `Add Python 3.X to PATH`. For more detailed instructions please see the -[official Python on Windows guide](https://docs.python.org/3.7/using/windows.html). - -## Install PyBaMM - -### User install -Launch the Command Prompt and go to the directory where you want to install PyBaMM. You can find a reminder of how to -navigate the terminal [here](http://www.cs.columbia.edu/~sedwards/classes/2015/1102-fall/Command%20Prompt%20Cheatsheet.pdf). - -We recommend to install PyBaMM within a virtual environment, in order not -to alter any distribution python files. - -To create a virtual environment `env` within your current directory type: - -```bash -python -m venv env -``` -You can then "activate" the environment using: - -```bash -env\Scripts\activate.bat -``` -Now all the calls to pip described below will install PyBaMM and its dependencies into -the environment `env`. When you are ready to exit the environment and go back to your -original system, just type: - -```bash -deactivate -``` - -PyBaMM can be installed via pip: -```bash -pip install pybamm -``` - -PyBaMM's dependencies (such as `numpy`, `scipy`, etc) will be installed automatically when you install PyBaMM using `pip`. - -For an introduction to virtual environments, see (https://realpython.com/python-virtual-environments-a-primer/). - -## Uninstall PyBaMM -PyBaMM can be uninstalled by running -```bash -pip uninstall pybamm -``` -in your virtual environment. - -## Installation using WSL -If you want to install the optional PyBaMM solvers, you have to use the Windows Subsystem for Linux (WSL). You can find -the installation instructions [here](INSTALL-WINDOWS-WSL.md). diff --git a/compiling-KLU.md b/compiling-KLU.md deleted file mode 100644 index ab74ee90b7..0000000000 --- a/compiling-KLU.md +++ /dev/null @@ -1,173 +0,0 @@ -# PyBaMM developer install - The KLU sparse solver -If you wish to try a different DAE solver, PyBaMM currently offers a direct interface to the sparse KLU solver within Sundials. -This solver comes as a C++ python extension module. -Therefore, when installing PyBaMM from source (e.g. from the GitHub repository), the KLU sparse solver module must be compiled. -Running `pip install .` or `python setup.py install ` in the PyBaMM directory will result in a attempt to compile the KLU module. - -Note that if CMake of pybind11 are not found (see below), the installation of PyBaMM will carry on, however skipping -the compilation of the `idaklu` module. This allows developers that are not interested in the KLU module to install PyBaMM from source without having to install the required dependencies. - -To build the KLU solver, the following dependencies are required: - -- A C++ compiler (e.g. `g++`) -- A Fortran compiler (e.g. `gfortran`) -- The python 3 header files -- [CMake](https://cmake.org/) -- A BLAS implementation (e.g. [openblas](https://www.openblas.net/)) -- [pybind11](https://github.com/pybind/pybind11) -- [sundials](https://computing.llnl.gov/projects/sundials) -- [SuiteSparse](http://faculty.cse.tamu.edu/davis/suitesparse.html) - -The first four should be available through your favourite package manager. -On Debian-based GNU/Linux distributions: -```bash -apt update -apt install python3-dev gcc gfortran cmake libopenblas-dev -``` - -## pybind11 -The pybind11 source directory should be located in the PyBaMM project directory at the time of -compilation. -Simply clone the GitHub repository, for example: -```bash -# In the PyBaMM project dir (next to setup.py) -git clone https://github.com/pybind/pybind11.git -``` -## SuiteSparse and sundials -### Method 1 - Using the convenience script -The PyBaMM repository contains a script `scripts/setup_KLU_module_build.py` that automatically -downloads, extracts, compiles and installs the two libraries. - -First install the Python `wget` module -``` -pip install wget -``` -Then execute the script -``` -# In the PyBaMM project dir (next to setup.py) -python scripts/setup_KLU_module_build.py -``` -The above will install the required component of SuiteSparse and Sundials in your home directory under -`~/.local/`. -Note that you can provide the option `--install-dir=` to install both libraries to -an alternative location. If `` is not absolute, it will be interpreted as relative to the PyBaMM project directory. - -Finally, reactivate your virtual environment by running -``` -source $(VIRTUAL_ENV)/bin/activate -``` -Alternatively, you update the `LD_LIBRARY_PATH` environment variable as follows -``` -export LD_LIBRARY_PATH=$(HOME)/.local:$LD_LIBRARY_PATH -``` -The above export statement will be ran automatically the next time you activate you python virtual environment. - -If did not run the convenience script inside a python virtual environment, execute you bash config file -``` -source ~/.bashrc -``` -(or start a new shell). - -Build files are located inside the PyBaMM project directory under `KLU_module_deps/`. -Feel free to remove this directory once everything is installed correctly. - -### Method 2 - Compiling Sundials (advanced) - -#### SuiteSparse -On most current linux distributions and macOS, a recent enough version of -the suitesparse source package is available through the package manager. -For instance on Fedora -``` -yum install libsuitesparse-dev -``` - -#### Sundials -The PyBaMM KLU solver requires Sundials >= 4.0. Because most Linux distribution provide older versions through -their respective package manager, it is recommended to build and install Sundials manually. - -First, download and extract the sundials 5.0.0 source -``` -wget https://computing.llnl.gov/projects/sundials/download/sundials-5.0.0.tar.gz . -tar -xvf sundials-5.0.0.tar.gz -``` -Then, create a temporary build directory and navigate into it -``` -mkdir build_sundials -cd build_sundials -``` -You can now configure the build, by running -``` -cmake -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\ - -DKLU_ENABLE=ON\ - -DKLU_INCLUDE_DIR=path/to/suitesparse/headers\ - -DKLU_LIBRARY_DIR=path/to/suitesparse/libraries\ - ../sundials-5.0.0 -``` -Be careful set the two variables `KLU_INCLUDE_DIR` and `KLU_LIBRARY_DIR` -to the correct installation location of the SuiteSparse libary on your system. -If you installed SuiteSparse through your package manager, this is likely to be something similar to: -``` --DKLU_INCLUDE_DIR=/usr/include/suitesparse\ --DKLU_LIBRARY_DIR=/usr/lib/x86_64-linux-gnu\ -``` -By default, Sundials will be installed on your system under `/usr/local` (this varies depending on the -distribution). -Should you wish to install sundials in a specific location, set the following variable -``` --DCMAKE_INSTALL_PREFIX=install/location\ -``` -Finally, build the library: -``` -make install -``` -You may be asked to run this command as a super-user, depending on the installation location. - -#### Alternative installation location -By default, it is assumed that the SuiteSparse and Sundials libraries are installed in your home directory -under `~/.local`. -If you installed the libraries to (a) different location(s), you must set the options -`suitesparse-root` or/and `sundials-root` when installing PyBaMM. -Examples: - -``` -python setup.py install --suitesparse-root=path/to/suitesparse -``` -or -``` -pip install . --install-option="--sundials-root=path/to/sundials" -``` - -## (re)Install PyBaMM to build the KLU solver -If the above dependencies are correctly installed, any of the following commands -will install PyBaMM with the `idaklu` solver module: -``` -pip install . -pip install -e . -python setup.py install -python setup.py develop -... -``` -Note that it doesn't matter if pybamm is already installed. The above commands will update your exisitng installation by adding the `idaklu` module. - -## Check that the solver is correctly installed -If you install PyBaMM in [editable mode](https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs) using the `-e` pip switch or if you use the `python setup.py install` command, a log file will be located in the project directory (next to the `setup.py` file). -``` -cat setup.log -020-03-24 11:33:50,645 - PyBaMM setup - INFO - Starting PyBaMM setup -2020-03-24 11:33:50,653 - PyBaMM setup - INFO - Not running on windows -2020-03-24 11:33:50,654 - PyBaMM setup - INFO - Could not find CMake. Skipping compilation of KLU module. -2020-03-24 11:33:50,655 - PyBaMM setup - INFO - Could not find pybind11 directory (/io/pybind11). Skipping compilation of KLU module. -``` - -If the KLU sparse solver is correctly installed, then the following command -should return `True`. -``` -$ python -c "import pybamm; print(pybamm.have_idaklu())" -``` From 97f172c8df1b270552475839dd90b48be130828a Mon Sep 17 00:00:00 2001 From: Thibault Lestang Date: Mon, 11 May 2020 18:51:42 +0100 Subject: [PATCH 7/7] Replace dead links in README by quickstart section #987 --- README.md | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index e7f74a89b6..485e1dba61 100644 --- a/README.md +++ b/README.md @@ -49,19 +49,24 @@ can be found For further examples, see the list of repositories that use PyBaMM [here](https://github.com/pybamm-team/pybamm-example-results) -## How can I obtain & install PyBaMM? - -### Linux - -For instructions on installing PyBaMM on Debian-based distributions, please see [here](INSTALL-LINUX-MAC.md). - -### Mac OS - -For instructions on installing PyBaMM on Mac OS distributions, please see [here](INSTALL-LINUX-MAC.md). +## How can I install PyBaMM? +PyBaMM is available on GNU/Linux, MacOS and Windows. +We strongly recommend to install PyBaMM within a python virtual environment, in order not to alter any distribution python files. +For instructions on how to create a virtual environment for PyBaMM, see [the documentation](https://pybamm.readthedocs.io/en/latest/install/GNU-linux.html#user-install). + +### Using pip +```bash +pip install pybamm +``` -### Windows +### Using conda +PyBaMM is available as a conda package through the conda-forge channel. +```bash +conda install -c conda-forge pybamm +``` -For instructions on installing PyBaMM on Windows distributions, please see [here](INSTALL-WINDOWS.md). If you want to install the optional solvers (such as scikits-odes and KLU solvers), install PyBaMM on the Windows Subsystem for Linux following the instructions [here](INSTALL-WINDOWS-WSL.md) +### Optional solvers +On GNU/Linux and MacOS, an optional [scikits.odes](https://scikits-odes.readthedocs.io/en/latest/)-based solver is available, see [the documentation](https://pybamm.readthedocs.io/en/latest/install/GNU-linux.html#scikits-odes-label). ## Citing PyBaMM