<commit_before>marbl
=====

Marginal based learning of Conditional Random Field parameters.

# Overview

This implementation roughly corresponds to the algorithm described in the paper:
 * <NAME>, [Learning Graphical Model Parameters with Approximate Marginal Inference](http://users.cecs.anu.edu.au/~jdomke/papers/2013pami.pdf), IEEE Transactions on Pattern Analysis, 2013.

# Requirements

* The only external requirement of Marbl is openMPI and a C++ compiler that supports C++11.  (i.e. a recent-ish one.)
 * While openMPI is often used on clusters, it is also efficient to use for inter-process communication between multiple processes on a single computer.  Thus, Marbl uses this single mechanism for parallelism, both on single machines and cluster.
 * On linux or Mac OS, openMPI is trivially installed using a package management system.  For example, using [homebrew](http://brew.sh/), one requires only `brew install openmpi`.
 * On Windows, pre-compiled binaries for Cygwin are available [here](http://www.open-mpi.org/software/ompi/v1.8/).

# Features

* Marbl can handle quite arbitrary problems, with factors of any size, and variables taking any number of values.
* Marbl uses [openMPI](http://www.open-mpi.org/) for parallelism.  This is trivial to use on a single machine to get your problem running.  (Essentially, you just install openMPI, and then compile using the provided scripts.)  Since almost all clusters provide MPI, you can also run Marbl on clusters of computers.  We have observed essentially linear speedups using up to several hundred cores.
* Marbl is a command-line tool, with inputs in very simple specified text formats.  Thus, you can use whatever (presumably high-level) language to create your problem, by writing a simple routine to produce the data and graph specifications in the appropriate format.

# Comparison with JGML

Marbl is similar to the [JGMT](http://users.cecs.anu.edu.au/~jdomke/JGMT/) toolbox, with the following differences:

* Language
 * JGMT is implemented in a mix of Matlab and C++, and must be used through Matlab.
 * Marbl is a command-line tool written in pure C++.  Interaction is via the command-line and text files specifying the data and structure of the graph.
 * However, one would typically create the inputs to Marbl using a high-level language, and some examples of this in Matlab are provided.

* Limitations
 * JGMT can only handle pairwise graphs.  Marbl can handle arbitrarily large factors.
 * JGMT assumes that all variables have the same possible number of values.  Marbl does not assume this.
 * JGMT is reasonably efficient.  Marbl is better still.

* Parallelism
 * Marbl uses openMPI for parallelism.  This can be used either on a single machine, or on a cluster of computers.
 * JGMT is parallel to some degree, using matlabs parfor mechanism.<commit_msg>Yet more docs!<commit_after>marbl
=====

Marginal based learning of Conditional Random Field parameters.

# Overview

This implementation roughly corresponds to the algorithm described in the paper:
 * <NAME>, [Learning Graphical Model Parameters with Approximate Marginal Inference](http://users.cecs.anu.edu.au/~jdomke/papers/2013pami.pdf), IEEE Transactions on Pattern Analysis, 2013.

# Getting started



# Requirements

Compiling Marbl requires a C++ compiler that supports C++11, and two easily-installed external projects.

For example, using [homebrew](http://brew.sh/) on Mac OS, these can be installed as `brew install liblbfgs` and `brew install openmpi`.

* [openMPI](http://www.open-mpi.org/) is a tool for parallel computing. While openMPI is typically used on clusters, it can manage communication between processes on a single computer.  Thus, Marbl uses this single mechanism for parallelism, both on single machines and clusters.
  * On linux or Mac OS, openMPI is trivially installed using your favorite package management system, as discussed above.
  * On Windows, pre-compiled binaries for Cygwin are available [here](http://www.open-mpi.org/software/ompi/v1.8/). 

* [libLBFG](http://www.chokkan.org/software/liblbfgs/) is a C library for the L-BFGS optimization algorithm.
 * On Linux or Mac OS, liblbfgs is trivially installed using your favorite package management system.

# Features

* Marbl can handle quite arbitrary problems, with factors of any size, and variables taking any number of values.
* Marbl uses [openMPI](http://www.open-mpi.org/) for parallelism.  This is trivial to use on a single machine to get your problem running.  (Essentially, you just install openMPI, and then compile using the provided scripts.)  Since almost all clusters provide MPI, you can also run Marbl on clusters of computers.  We have observed essentially linear speedups using up to several hundred cores.
* Marbl is a command-line tool, with inputs in very simple specified text formats.  Thus, you can use whatever (presumably high-level) language to create your problem, by writing a simple routine to produce the data and graph specifications in the appropriate format.

# Comparison with JGML

Marbl is similar to the [JGMT](http://users.cecs.anu.edu.au/~jdomke/JGMT/) toolbox, with the following differences:

* Language
 * JGMT is implemented in a mix of Matlab and C++, and must be used through Matlab.
 * Marbl is a command-line tool written in pure C++.  Interaction is via the command-line and text files specifying the data and structure of the graph.
 * However, one would typically create the inputs to Marbl using a high-level language, and some examples of this in Matlab are provided.

* Limitations
 * JGMT can only handle pairwise graphs.  Marbl can handle arbitrarily large factors.
 * JGMT assumes that all variables have the same possible number of values.  Marbl does not assume this.
 * JGMT is reasonably efficient.  Marbl is better still.

* Parallelism
 * Marbl uses openMPI for parallelism.  This can be used either on a single machine, or on a cluster of computers.
 * JGMT is parallel to some degree, using Matlab’s parfor mechanism.  However, this requires the (expensive) parallel computing toolbox to use up to 12 cores, and the (yet more expensive) distributed computing toolbox to use more than that.

* Acknowledgements

Marbl includes the code for Eigen.

* [Eigen](http://eigen.tuxfamily.org/index.php?title=Main_Page), a template library for linear algebra.

Note that Eigen is under the [Mozilla public license](http://www.mozilla.org/MPL/2.0), which places some (very minor) restrictions on how it (and thus Marbl) can be used.
{'fraction_non_alphanumeric': 0.0666360294117647, 'fraction_numerical': 0.00428921568627451, 'mean_word_length': 4.395867768595041, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 7, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1807687', 'n_tokens_mistral': 1776, 'n_tokens_neox': 1675, 'n_words': 884}