extending.tex

\subsection{User-defined functions}\label{user-defined-function-section}

A user-defined function must extend \verb|blog.model.AbstractFunctionInterp|
and provide a constructor that takes a single \verb|List| argument. When
compiling the class defining the user-defined function, you must add the \bl
JAR file to the class path.

Here is an example user-defined function computing the logarithm in base 10 of
a number:

\begin{minted}{java}
package my_package;

import java.util.List;

import blog.model.AbstractFunctionInterp;

public class Log10Interp extends AbstractFunctionInterp {
  public Log10Interp(List args) {
  }

  public Object getValue(List args) {
    final double value = ((Number) args.get(0)).doubleValue();
    return Math.log10(value);
  }
}
\end{minted}

To use this function from a model, declare it like this:

\begin{blogcode}
fixed Real log10(Real val) = my_package.Log10Interp();
\end{blogcode}

Then \verb|log10| can be used just like any other fixed function, e.g.
\verb|query log10(100.0)|.

Make sure \verb|my_package| is on the class path. If you get an error like "No
definition found for non-random function log10", you most likely have a
class-path problem. If \verb|my_package| is in the current working directory,
you need not do anything. Otherwise, if \verb|my_package| lives at
\verb|/some/absolute/path/my_package|, launch \bl with an environment variable:
{\tt CLASSPATH=/some/absolute/path blog model.blog}.

For more advanced examples of user-defined functions, see
\verb|blog.distrib.ListInterp| and \verb|blog.distrib.TabularInterp|.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{User-defined distributions}\label{user-defined-distribution-section}

Probability distributions are implemented in Java.  Distribution classes should implement the interface \verb|blog.distrib.CondProbDistrib|. 
By default, the \bl engine will look up distribution classes in the package \verb|blog.distrib|. In addition, it will look up distribution classes under the default empty package. 

Below is one example of a uniform distribution on Integers.
\begin{minted}{java}
package blog.distrib;

import blog.common.Util;

public class UniformInt implements CondProbDistrib {

  /**
   * set parameters for UniformInt
   * distribution
   * 
   * @param params
   *          An array of [Integer, Integer]
   *          <ul>
   *          <li>params[0]: <code>lower</code> (Integer)</li>
   *          <li>params[1]: <code>upper</code> (Integer)</li>
   *          </ul>
   * 
   * @see blog.distrib.CondProbDistrib#setParams(java.util.List)
   */
  @Override
  public void setParams(Object[] params) {
    if (params.length != 2) {
      throw new IllegalArgumentException("expected two parameters");
    }
    setParams((Integer) params[0], (Integer) params[1]);
  }

  /**
   * For a non-null value of method parameter lower, sets the
   * distribution parameter <code>lower</code> to method 
   * parameter lower. Similarly for <code>upper</code>. 
   * Then checks to see if assignment of parameters is legal. 
   * In other words, an assignment of parameters is legal
   * if <code>lower <= upper</code>.
   * 
   * @param lower
   *          parameter <code>lower</code>
   * @param upper
   *          parameter <code>upper</code>
   */
  public void setParams(Integer lower, Integer upper) {
    if (lower != null) {
      this.lower = lower;
      this.hasLower = true;
    }
    if (upper != null) {
      this.upper = upper;
      this.hasUpper = true;
    }
    if (this.hasLower && this.hasUpper) {
      if (this.lower > this.upper) {
        throw new IllegalArgumentException(
            "UniformInt distribution requires that lower <= upper");
      }
      this.prob = 1.0 / (this.upper - this.lower + 1);
      this.logProb = Math.log(this.prob);
    }
  }

  private void checkHasParams() {
    if (!this.hasLower) {
      throw new IllegalArgumentException("parameter lower not provided");
    }
    if (!this.hasUpper) {
      throw new IllegalArgumentException("parameter upper not provided");
    }
  }

  /*
   * (non-Javadoc)
   * 
   * @see blog.distrib.CondProbDistrib#getProb(java.lang.Object)
   */
  @Override
  public double getProb(Object value) {
    return getProb(((Integer) value).intValue());
  }

  /**
   * Returns the probability of the UniformInt distribution having 
   * outcome <code>value</code>.
   */
  public double getProb(int value) {
    checkHasParams();
    return (value >= lower) && (value <= upper) ? prob : 0;
  }

  /*
   * (non-Javadoc)
   * 
   * @see blog.distrib.CondProbDistrib#getLogProb(java.lang.Object)
   */
  @Override
  public double getLogProb(Object value) {
    return getLogProb(((Integer) value).intValue());
  }

  /**
   * Returns the log probability of the UniformInt distribution having outcome
   * <code>value</code>.
   */
  public double getLogProb(int value) {
    checkHasParams();
    return ((value >= lower) && (value <= upper)) ? logProb
        : Double.NEGATIVE_INFINITY;
  }

  /*
   * (non-Javadoc)
   * 
   * @see blog.distrib.CondProbDistrib#sampleVal()
   */
  @Override
  public Object sampleVal() {
    return sample_value();
  }

  public int sample_value() {
    checkHasParams();
    return lower + Util.randInt(upper - lower + 1);
  }

  @Override
  public String toString() {
    return getClass().getName();
  }

  /** Parameter <code>lower</code>. */
  private int lower;
  /** Flag indicating whether <code>lower</code> has been set. */
  private boolean hasLower;
  /** Parameter <code>upper</code>. */
  private int upper;
  /** Flag indicating whether <code>upper</code> has been set. */
  private boolean hasUpper;
  /**
   * The probability of an outcome between <code>lower</code> and
   * <code>upper</code> inclusive.
   */
  private double prob;
  /**
   * The log probability of an outcome between <code>lower</code> and
   * <code>upper</code> inclusive.
   */
  private double logProb;
}
\end{minted}