Installation

Docker

Katydid is available in a Docker container. You can start up a Katydid container with the following command:

host> docker run -it –rm project8/katydid:latest /bin/bash

In the container you need to source two scripts to fully setup the environment.

docker> source $KATYDID_BUILD_PREFIX/setup.sh docker> source $KATYDID_BUILD_PREFIX/bin/this_katydid.sh

Operating System Support

  • Mac OS X (usually tested on OS X 10.10 and 10.11)

  • Linux (usually tested on Debian Jessie and Scientific Linux 6)

Source

Katydid source can be found on the Project 8 Github repository https://github.com/project8/katydid. The master branch of the source code can be cloned from the Github repository in the standard way (assuming you have Git installed and configured on your computer):

Dependencies

External

  • CMake (3.1 or better)

  • Boost (date_time, filesystem, program_options, system, thread; 1.46 or better)

  • HDF5 (optional, but required by Monarch3 and for outputing to HDF5 files)

  • Protobuf (optional, but required by Monarch2)

  • FFTW3 (optional, but required to do FFTs; 3.3 or newer)

  • ROOT (optional, but required for some processors and outputing to ROOT files; 6.0 or better)

  • MatIO (optional, but required to read the Matlab files generated by the Tektronix RSA; 1.5.0 or better)

  • GraphicsMagick (optional, but required for writing images)

  • Eigen (not currently used)

Submodules (included with Katydid; must be fetched via Git)

Distributed Code (included with Katydid directly)

  • nanoflann

  • RapidXML

Tips on Installing the Dependencies

MacOS: Homebrew is a convenient package manager. Before using it for the installation, make sure that the version available on brew is compatible with what is listed in the dependency list above. CMake, Boost, Hdf5, Protobuf, and Root are all available through brew via the instructions in these links.

Installation

The following steps will build Katydid from scratch. Starting with a terminal window …

  1. Clone the repository and make a build directory as recommended above. You will also have to initialize the submodules.

    $ git clone "https://github.com/project8/Katydid"
$ cd Katydid
$ git submodule update --init --recursive
$ mkdir build

  2. To configure the installation you can use cmake, ccmake, or cmake-gui.

    For a first configuration, using either ccmake or cmake-gui is highly recommended. The following instructions are for ccmake, but the steps with cmake-gui would be approximately the same.

    $ cd build
$ ccmake ..

    You will be prompted to press [c] to configure, and the window will fill up with several options.

    You should set the CMake variable CMAKE_BUILD_TYPE to either RELEASE, STANDARD, or DEBUG (default), in order of how much text output you would like (from least to most) and how much compiler optimization should be performed (from most to least). You may wish to to activate C++14 support with USE_CPP14=ON if your ROOT version was built with C++14 support.

    Variables that start with Katydid_ will control which parts of Katydid are built.

    If using Monarch, if you want to read egg3 files, ensure that Monarch_BUILD_MONARCH3 is set. If you want to read egg2 files, ensure that Monarch_BUILD_MONARCH2 is set.

    The install prefix is specified by the CMake variable CMAKE_INSTALL_PREFIX. The library, binaries, and header files will be installed in the lib, bin, and include subdirectories. The default install prefix is the build directory.

    After you’ve finished, if you’ve changed anything press [c] again to configure. Then [g] to generate and exit.

  3. Build and install.

    $ make install

    Or if you want to take advantage of parallel building to get things done faster:

    $ make -j install

    If the compiler runs into errors during the build, first check that you’ve updated the submodules and that you have all of the required dependencies installed (many are called “optional” on this page, but if you want to build without them you must also specify this in the cmake window). If you made a change to the dependencies or submodules, you may have to wipe the build directory and start again from step 1; simply writing make install again will not always work.