Skip to content

Commit

Permalink
Update installation guidelines
Browse files Browse the repository at this point in the history
  • Loading branch information
@dalg24
dalg24 committed Sep 7, 2016
1 parent e20a4d3 commit 6625868
Showing 1 changed file with 60 additions and 118 deletions.
178 changes: 60 additions & 118 deletions docs/source/install.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,23 +3,14 @@
Installation
============

This section provide guidelines for installing cap and its TPLs.
We recommend out-of-source builds.
This section provide guidelines for installing Cap from source.

.. code::
$ export PREFIX=/path/to/some/working/directory/for/the/project
$ mkdir -p ${PREFIX}
$ mkdir ${PREFIX}/archive
$ mkdir ${PREFIX}/source
$ mkdir ${PREFIX}/build
$ mkdir ${PREFIX}/install
Install third-party libraries
-----------------------------
Note that it is **not** necessary to build Cap from source to use it. Refer to
the :ref:`Docker<docker>` section for instructions on how to pull the latest
image of Cap.

Cap has a required dependency on C++14.
Third-party libraries
---------------------

+-----------------------------+------------+---------+
| Packages | Dependency | Version |
Expand All @@ -33,107 +24,81 @@ Cap has a required dependency on C++14.
| deal.II with p4est/Trilinos | Optional | 8.4.0 |
+-----------------------------+------------+---------+

Cap and its dependencies may be built using `spack
<https://github.com/llnl/spack>`_. You would need to install the following
packages:

.. code::
$ spack install boost +graph +icu_support +mpi +python
$ spack install trilinos ~hypre ~mumps +boost \
^boost+graph+icu_support+mpi+python
$ spack install dealii~arpack~gsl~oce~petsc+trilinos+mpi \
^trilinos~hypre~mumps ^boost+graph+icu_support+mpi+python
$ spack install py-mpi4py
$ spack install py-matplotlib
$ spack install py-h5py
Before buiding Cap, you would then need to load the following modules: dealii,
boost, mpi, cmake, python, py-mpi4py, py-matplotlib, py-parsing, py-numpy, and
py-h5py.

Message Passing Interface (MPI)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Cap should be working with any of the MPI implementations. It has only been
tested with Open MPI, MPICH, and Intel MPI.

Boost
^^^^^
Boost version 1.59.0 or later is required.
Boost can be downloaded from `here <http://www.boost.org/users/download>`_.
Make sure to install **all** the libraries.
Do not forget to add the ``using mpi ;`` directive to the
`project-config.jam` file before building boost.

Assuming that you have downloaded `boost_1_59_0.tar.bz2` into the
`${PREFIX}/archive` directory, boost may be installed by running:

.. code::
$ mkdir ${PREFIX}/source/boost
$ tar -xf ${PREFIX}/archive/boost_1_59_0.tar.bz2 -C ${PREFIX}/source/boost --strip-components=1
$ cd ${PREFIX}/source/boost && ./bootstrap.sh --prefix=${PREFIX}/install/boost
$ echo "using mpi ;" >> project-config.jam
$ ./b2 install -j<N> variant=release cxxflags="-std=c++14"
Boost version 1.59.0 or later is required. Boost can be downloaded from `here
<http://www.boost.org/users/download>`_. Make sure to install **all** the
libraries. Do not forget to add the ``using mpi ;`` directive to your
``project-config.jam`` file before building.

deal.II
^^^^^^^
The open source finite element library deal.II is optional. It is only required
to work with energy storage devices of type ``SuperCapacitor``. Version 8.4.0 or
later compiled with C++14/MPI/Boost/p4est/Trilinos support is required. The
development sources can be found `here <https://github.com/dealii/dealii>`_.
Please refer to the deal.II documentation to see how to install `p4est
<https://dealii.org/developer/external-libs/p4est.html>`_ and `Trilinos
<https://dealii.org/developer/external-libs/trilinos.html>`_.

The open source finite element library deal.II is optional.
It is only required to work with energy storage devices of type ``SuperCapacitor``.
Version 8.4.0 or later compiled with C++14/MPI/Boost/p4est/Trilinos support is required.
The development sources can be found `here <https://github.com/dealii/dealii>`_.

To download the release version 8.4.0, do:

.. code::
$ wget --output-document=${PREFIX}/archive/dealii-8.4.0.tar.gz \
https://github.com/dealii/dealii/releases/download/v8.4.0/dealii-8.4.0.tar.gz
$ mkdir ${PREFIX}/source/dealii && tar -xf ${PREFIX}/archive/dealii-8.4.0.tar.gz \
-C ${PREFIX}/source/dealii --strip-components=1
It is a good idea to make a `configure_dealii` script such as:

.. code-block:: bash
:linenos:
EXTRA_ARGS=$@
cmake \
-D CMAKE_INSTALL_PREFIX=${PREFIX}/install/dealii \
-D CMAKE_BUILD_TYPE=Release \
-D DEAL_II_WITH_CXX14=ON \
-D DEAL_II_WITH_MPI=ON \
-D BOOST_DIR=${PREFIX}/install/boost \
-D P4EST_DIR=${PREFIX}/install/p4est \
-D TRILINOS_DIR=${PREFIX}/install/trilinos \
$EXTRA_ARGS \
${PREFIX}/source/dealii
Then run:

.. code::

$ mkdir ${PREFIX}/build/dealii && cd ${PREFIX}/build/dealii
$ ../configure_dealii
$ make -j<N> install
Please refer to the deal.II documentation to see how to install
`p4est <https://dealii.org/developer/external-libs/p4est.html>`_ and
`Trilinos <https://dealii.org/developer/external-libs/trilinos.html>`_.

Install cap from source
Install Cap from source
-----------------------
Get the source:

.. code::
$ git clone https://github.com/ORNL-CEES/cap.git ${PREFIX}/source/cap
$ git clone https://github.com/ORNL-CEES/Cap.git && cd Cap
Create a `configure_cap` script in `${PREFIX}/build`:
Create a ``configure_cap.sh`` script such as:

.. code-block:: bash
:linenos:
#!/usr/bin/env bash
EXTRA_ARGS=$@
cmake \
-D CMAKE_INSTALL_PREFIX=${PREFIX}/install/cap \
-D BOOST_DIR=${PREFIX}/install/boost \
-D CMAKE_INSTALL_PREFIX=<your/install/prefix/here> \
-D BOOST_DIR=<path/to/boost> \
-D ENABLE_DEAL_II=ON \
-D DEAL_II_DIR=${PREFIX}/install/dealii \
-D DEAL_II_DIR=<path/to/dealii> \
$EXTRA_ARGS \
${PREFIX}/source/cap
..
Configure, build and install:

.. code::
$ mkdir ${PREFIX}/build/cap
$ cd ${PREFIX}/build/cap
$ ../configure_cap
$ mkdir build && cd build
$ vi configure_cap.sh
$ chmod +x configure_cap.sh
$ ./configure_cap.sh
$ make -j<N> && make install
Expand All @@ -147,23 +112,23 @@ Run the tests:
Enable the Python wrappers
--------------------------

To build the Python wrappers cap must be configured with an extra flag
``ENABLE_PYTHON=ON``. It is recommended to use Python 3.X but PyCap has
been successfully built with Python 2.X in the past.
To build the Python wrappers Cap must be configured with an extra flag ``-D
ENABLE_PYTHON=ON``. It is recommended to use Python 3.X but Cap has been
successfully built with Python 2.X in the past.

.. code::
$ ../configure_cap -DENABLE_PYTHON=ON
$ ../configure_cap.sh -D ENABLE_PYTHON=ON
$ make install
Prepend the `cap/python` directory to the environment variable `PYTHONPATH`
Prepend the Python install directory to your ``PYTHONPATH`` environment variable
in order to import the pycap module from your Python interpreter.

.. code::
$ export PYTHONPATH=${PREFIX}/install/cap/lib/pythonX.Y/site-packages:${PYTHONPATH}
$ export PYTHONPATH=<cap/install/prefix>/lib/pythonX.Y/site-packages:${PYTHONPATH}
``X.Y`` stands for the version of Python that was used to build PyCap,
``X.Y`` stands for the version of Python that was used to build Cap,
for example 2.7 or 3.5.

Launch Python and try:
Expand All @@ -173,12 +138,8 @@ Launch Python and try:
>>> import pycap
>>> help(pycap)

A number of Python packages are required to use pycap. We recommend you use
pip to install them:

.. code::
$ pip install numpy scipy matplotlib cython h5py mpi4py
Note that a number of Python packages are required to use pycap: numpy,
matplotlib, mpi4py, and h5py.


Build this documentation
Expand All @@ -188,26 +149,7 @@ Run the configuration script with the extra flag:

.. code::
$ ../configure_cap -DENABLE_DOCUMENTATION=ON
$ ../configure_cap.sh -D ENABLE_DOCUMENTATION=ON
Open the file `index.html` in the directory `docs/html`.


Install TPLs using spack
------------------------

Cap and its dependencies can be build using `spack <https://github.com/llnl/spack>`_.
After installing spack, you need to install the following packages:

.. code::
$ spack install boost +graph +icu_support +mpi +python
$ spack install trilinos ~hypre ~mumps +boost ^boost+graph+icu_support+mpi+python
$ spack install dealii~arpack~gsl~oce~petsc+trilinos+mpi \
^trilinos~hypre~mumps ^boost+graph+icu_support+mpi+python
$ spack install py-mpi4py
$ spack install py-matplotlib
$ spack install py-h5py
Open the file ``index.html`` in the directory ``docs/html``.

Before compiling Cap, you need to load the following modules: dealii, boost,
mpi, cmake, python, py-mpi4py, py-matplotlib, py-parsing, py-numpy, and py-h5py.

0 comments on commit 6625868

Please sign in to comment.