.. _chemfp-api:

chemfp API
==============

This chapter contains the docstrings for the public portion of the
chemfp API. Chemfp also has internal modules and functions that should
not be imported or used directly. If you use parts of the undocumented
API then your code is more likely to break with newer chemfp releases.

See ":ref:`getting_started_api`" for some introductory examples.


.. toctree::
   :maxdepth: 2
   :titlesonly:

   chemfp top-level <chemfp_toplevel>
   chemfp.arena <chemfp_arena>
   chemfp.base_toolkit <chemfp_base_toolkit>
   chemfp.bitops <chemfp_bitops>
   chemfp.cdk_toolkit <chemfp_cdk_toolkit>
   chemfp.cdk_types <chemfp_cdk_types>
   chemfp.diversity <chemfp_diversity>
   chemfp.encodings <chemfp_encodings>
   chemfp.fpb_io <chemfp_fpb_io>
   chemfp.fps_io <chemfp_fps_io>
   chemfp.fps_search <chemfp_fps_search>
   chemfp.highlevel.conversion <chemfp_highlevel_conversion>
   chemfp.highlevel.diversity <chemfp_highlevel_diversity>
   chemfp.highlevel.similarity <chemfp_highlevel_similarity>
   chemfp.io <chemfp_io>
   chemfp.openbabel_toolkit <chemfp_openbabel_toolkit>
   chemfp.openbabel_types <chemfp_openbabel_types>
   chemfp.openeye_toolkit <chemfp_openeye_toolkit>
   chemfp.openeye_types <chemfp_openeye_types>
   chemfp.rdkit_toolkit <chemfp_rdkit_toolkit>
   chemfp.rdkit_types <chemfp_rdkit_types>
   chemfp.search <chemfp_search>
   chemfp.text_records <chemfp_text_records>
   chemfp.text_toolkit <chemfp_text_toolkit>
   chemfp.types <chemfp_types>

Overview
----------------------
   
The top-level chemfp module is the starting point for using chemfp. It
contains functions to read and write fingerprint files, "high-level"
commands for working with chemfp, and more.

The API for the FPS and FPS fingerprint readers and writers are
defined in ``chemfp.fps_io`` and ``chemfp.fpb_io``, which may refer to
a Location object defined in ``chemfp.io``.

The fingerprint arena class is defined in ``chemfp.arena``.

The chemfp.search module contains similarity search functions for
searching fingerprint arenas, and the search result class
definitions. This is a more low-level API than using
``chemfp.simsearch``.

The chemfp.fps\_search module contains similarity search functions for
searching FPS files, and the search result class definitions. This is only
needed when working in a streaming environment where fingerprint arena
creation overhead is too large.

The chemfp.diversity module contains chemfp's diversity pickers, all
of which require a fingerprint arena. This is a more low-level API
than using ``chemfp.maxmin``, ``chemfp.heapsweep``, or
``chemfp.spherex``.

The ``chemfp.cdk\_toolkit``, ``chemfp.openbabel\_toolkit``,
``chemfp.openeye\_toolkit`` and ``chemfp.rdkit\_toolkit`` contain the
public-facing API for chemfp's cheminformatics toolkit wrapper
implementations.

Sometimes you need to work with SMILES or SD files as text records,
not molecules. For that, use the ``chemfp.text\_toolkit`` module.

The ``chemfp.bitops`` module has functions to work with fingerprints
represented as byte strings or hex-encoded strings, as well as
configuration functions for configuring chemfp's bit operations. Use
the ``chemfp.encodings`` to decode from various fingerprint string
representations to a byte string.

Finally, the ``chemfp.types`` module contains a few public exceptions
which derived from ValueError but which don't yet also derive from
ChemFPError.