***********
 Installing
***********

Chemfp 3.4 is available as a pre-compiled package or a source
distribution.

Installing a pre-compiled package
=================================

Pre-compiled packages for chemfp are available for Python 2.7, Python
3.6, Python 3.7, and Python 3.8. They were compiled under the
"manylinux1" and "manylinux2014" Docker build environment, which means
they should work for most Linux-based operating systems.

These binary packages are NOT open source. By default they are
distributed under the Chemfp Base License Agreement v1.1, which
lets you use some of the chemfp functionality for internal purposes,
including the ability to create FPS files and use the "toolkit" APIs.

However, the following features require a time-limited license key:

- generate FPB files
- create or search in-memory fingerprint arenas with more than 50,000 fingerprints
- perform Tversky searches
- perform Tanimoto searches of FPS files with more than 20 queries at a time.

These features can be enabled with a valid license key, set via the
environment variable ``CHEMFP_LICENSE``.  Email
sales@dalkescientific.com to request a evaluation license or to
purchase a license.

Use the following command to install a pre-compiled version of
chemfp::

  python -m pip install chemfp -i https://chemfp.com/packages/ 


Installing from source
================================

The chemfp source distribution requires that Python and a C compiler
be installed in your machines. Since chemfp doesn't run on Microsoft
Windows (for tedious technical reasons), then your machine likely
already has both Python and a C compiler installed. In case you don't
have Python, or you want to install a newer version, you can download
a copy of Python from http://www.python.org/download/ . If you don't
have a C compiler, .. well, do I really need to give you a pointer for
that?

You may use chemfp 3.4 with either Python 2.7, or Python 3.6 or
newer.

The core chemfp functionality does not depend on a third-party library
but you will need a chemistry toolkit in order to generate new
fingerprints from structure files. chemfp supports the free Open Babel
and RDKit toolkits and the proprietary OEChem toolkit. Make sure you
install the Python libraries for the toolkit(s) you select.

The easiest way to install chemfp is with the `pip
<https://pip.pypa.io/>`_ installer. This comes with Python 2.7.9 or
later, and with Python 3.4 and later so is almost certainly installed
if you have Python. To install the source distribution ``tar.gz`` file
with pip::

  python -m pip install chemfp-3.4.tar.gz

Otherwise you can use Python's standard "setup.py". Read
http://docs.python.org/install/index.html for details of how to use
it. The short version is to do the following::

  tar xf chemfp-3.4.tar.gz
  cd chemfp-3.4
  python setup.py build
  python setup.py install

The last step may need a ``sudo`` if you otherwise cannot write to your
Python site-package. Another option is to use a `virtual environment
<https://pypi.python.org/pypi/virtualenv>`_.

Configuration options
=====================

The setup.py file has several compile-time options which can be set
either from the ``python setup.py build`` command-line or through
environment variables. The environment variable solution is the
easiest way to change the settings under pip.

.. option:: --with-openmp, --without-openmp

Chemfp uses OpenMP to parallelize multi-query searches. The default is
:option:`--with-openmp`. If you have a very old version of gcc, or an
older version of clang, or are on a Mac where the clang version
doesn't support OpenMP, then you will need to use
:option:`--without-openmp` to tell setup.py to compile without OpenMP::
   
   python setup.py build --without-openmp

You can also set the environment variable CHEMFP_OPENMP to "1" to
compile with OpenMP support, or to "0" to compile without OpenMP
support::
   
   CHEMFP_OPENMP=0 python -m pip install chemfp-3.4.tar.gz 

Note: you can use the environment variable ``CC`` to change the C
compiler. For example, the clang compiler on Mac doesn't support
OpenMP so I installed gcc-6 and compile using::

  CC=gcc-6 LDFLAGS="-L/usr/local/lib -lomp" \
      python -m pip install chemfp-3.4.tar.gz 

(Hmm. Perhaps I should upgrade my copy of gcc.)
      
.. option:: --with-ssse3, --without-ssse3

Chemfp by default compiles with SSSE3 support, which was first
available in 2006 so almost certainly available on your Intel-like
processor. In case I'm wrong (are you compiling for ARM? If so, send
me any compiler patches), you can disable SSSE3 support using the
:option:`--without-ssse3`, or set the environment variable
``CHEMFP_SSSE3`` to "0".

Compiling with SSSE3 support has a very odd failure case. If you
compile with the SSSE3 flag enabled, then take the binary to a machine
without SSSE3 support, then it will crash because all of the code will
be compiled to expect the SSSE3 instruction set even though only one
file, popcount_SSSE3.c, should be compiledthat way.

.. option:: --with-avx2, --without-avx2

Chemfp 3.0 added support for the AVX2 instruction set. This can be 30%
faster than the POPCNT instruction for 1024 or 2048 bit
fingerprints. By default it is enabled, and chemfp checks that the
chip implements AVX2 before calling the functions which are explicitly
written with AVX2.

Use :option:`--without-avx2` or set the environment variable
``CHEMFP_AVX2`` to "0" to disable it.