project8 / katydid

Project 8 data analysis package
Other
5 stars 4 forks source link

Katydid

Katydid is a data analysis package for Project 8.

The various actions Katydid can perform on data are packaged into Processors, which can be setup at runtime into any number of configurations to suit any analysis procedure.

Dependencies

External

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

Distributed Code (included with Katydid directly)

Operating System Support

Directory Structure

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.

Installing

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.

Instructions for Use

Katydid is typically started with a command like:

  > Katydid -c my_config_file.json

For more detailed instructions, use Katydid -h

Documentation

Hosted at: http://www.project8.org/katydid

Reference guide included with Katydid at Documentation/ReferenceGuide/html/index.html

Development

The Git workflow used is git-flow:

Issues should be posted via GitHub.