allnn_main.cc

Go to the documentation of this file.

/* MLPACK 0.2
 *
 * Copyright (c) 2008, 2009 Alexander Gray,
 *                          Garry Boyer,
 *                          Ryan Riegel,
 *                          Nikolaos Vasiloglou,
 *                          Dongryeol Lee,
 *                          Chip Mappus, 
 *                          Nishant Mehta,
 *                          Hua Ouyang,
 *                          Parikshit Ram,
 *                          Long Tran,
 *                          Wee Chin Wong
 *
 * Copyright (c) 2008, 2009 Georgia Institute of Technology
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 * 02110-1301, USA.
 */
// To begin, note the "@file" at the top of the previous comment
// block.  This tells Doxygen to parse the file; accordingly, a
// similar line should appear at the top of all of your files.

// Reusable code should be linked through a librule's header file.
#include "allnn.h"

// While not strictly required for parameter parsing, etc., fx will
// gently remind us (read: spew warning messages) if we do not
// document our parameters, timers, and results in a structure like
// the following.  Documentation may be accessed via --help.

const fx_entry_doc allnn_main_entries[] = {
  {"r", FX_REQUIRED, FX_STR, NULL,
   "  A file containing reference data.\n"},
  {"q", FX_PARAM, FX_STR, NULL,
   "  A file containing query data (defaults to r).\n"},
  {"do_naive", FX_PARAM, FX_BOOL, NULL,
   "  Whether to perform naive computation as well.\n"},
  {"output_filename", FX_PARAM, FX_STR, NULL,
   "  A file to receive the results of computation.\n"},
  FX_ENTRY_DOC_DONE
};

const fx_submodule_doc allnn_main_submodules[] = {
  {"allnn", &allnn_doc,
   "  Responsible for dual-tree computation.\n"},
  {"naive", &allnn_naive_doc,
   "  Stores results for naive computation.\n"},
  FX_SUBMODULE_DOC_DONE
};

const fx_module_doc allnn_main_doc = {
  allnn_main_entries, allnn_main_submodules,
  "This is an example program written to demonstrate FASTlib components.\n"
  "It performs the all-nearest-neighbors dual-tree computation.\n"
};

int main(int argc, char* argv[]) {

  // Always initialize FASTexec with main's inputs at the beggining of
  // your program.  This reads the command line, among other things.
  fx_module *root = fx_init(argc, argv, &allnn_main_doc);


  // The reference data file is a required parameter.
  const char* references_file_name = fx_param_str_req(root, "r");

  // The query data file defaults to the references.
  const char* queries_file_name =
      fx_param_str(root, "q", references_file_name);

  // FASTlib classes only poison data in their default constructors;
  // declarations must be followed by Init or an equivalent function.
  Matrix references;
  Matrix queries;

  // data::Load inits a matrix with the contents of a .csv or .arff.
  data::Load(references_file_name, &references);
  data::Load(queries_file_name, &queries);


  AllNN allnn;

  // FASTexec organizes parameters and results into submodules.  Think
  // of this as creating a new folder named "allnn_module" under the
  // rood directory (NULL) for the AllNN object to work inside.  Here,
  // we initialize it with all parameters defined "--allnn/...=...".
  struct datanode* allnn_module =
      fx_submodule(root, "allnn");

  // The Init function readies our object for action.  In this
  // example, we built the AllNN class to expect all of its inputs at
  // the time of Init; other designs might do things differently.
  allnn.Init(queries, references, allnn_module);

  // ArrayLists are prefered over standard C/C++ arrays.  These grow
  // dynamically and check bounds when compiled with "--mode=debug".
  // An index_t is an integer with compile-time specified size.
  ArrayList<index_t> results;

  // Tell the AllNN object to perform its computation.  We pass it a
  // fresh ArrayList by pointer (hence the &) as a mental note that
  // this input will be modified, i.e. filled with results.
  allnn.ComputeNeighbors(&results);


  /* Compare results with naive if run with "--do_naive=true" */
  if (fx_param_bool(root, "do_naive", 0)) {

    // Our design of the AllNN class renders it usable only once;
    // different code could clean out intermediate results, but for
    // this example, we'll just create another instance.
    AllNN naive_allnn;

    // This time we'll use a different Init function so we can avoid
    // building the tree.  Also, note that submodules and parameters
    // may be created/accessed in-line.  (More on this shortly.)
    naive_allnn.InitNaive(queries, references,
        fx_submodule(root, "naive"));

    ArrayList<index_t> naive_results;
    naive_allnn.ComputeNaive(&naive_results);

    /* Perform a quick sanity check now that we have naive results */

    // We don't want to run the for-loop unless debugging, hence the
    // #ifdef.  For debug-only one-liners, use DEBUG_ONLY(expr) or the
    // other debugging macros.  See base/debug.h for more details.
#ifdef DEBUG
    for (index_t i = 0; i < results.size(); ++i) {
      // Prints a message if results are different.  Note the peculiar
      // syntax "%"LI"d" used to properly format index_t values; this
      // alerts printf that index_t is long if compiled as such.
      DEBUG_WARN_MSG_IF(results[i] != naive_results[i],
          "i = %"LI"d, results[i] = %"LI"d, naive_results[i] = %"LI"d",
          i, results[i], naive_results[i]);
    }
#endif /* DEBUG */

  } /* if do_naive */


  const char* output_filename =
      fx_param_str(root, "output_filename", "output.txt");

  // We encourage you to use C-style file streams and print buffers
  // rather than C++'s complicated equivalents.
  FILE* output_file = fopen(output_filename, "w");

  // The ot namespace stands for object traversal and provides many
  // features.  Here, we pretty-print an ArrayList to file, though we
  // could alternately have serialized it for later loading and reuse.
  //
  // Note that this doesn't write a .csv, but instead a transcript of
  // the ArrayList's contents.  The library does not appear to have a
  // .csv writer for ArrayLists--this will be addressed.  You can
  // write .csv from Matrix objects with data::save.
  ot::Print(results, "neighbors", output_file);

  // Don't forget these things!
  fclose(output_file);

  // We must tell FASTexec to wrap up when our code is done.  This
  // emits its complete data structure--parameter settings, timers,
  // and stored results--to stdout unless you call fx_silence first.
  fx_done(root);

  // main should return 0 if the program terminates normally.
  return 0;

} /* main */