/*
 * File:                MonteCarloSampler.java
 * Authors:             Kevin R. Dixon
 * Company:             Sandia National Laboratories
 * Project:             Cognitive Foundry
 * 
 * Copyright Feb 4, 2010, Sandia Corporation.
 * Under the terms of Contract DE-AC04-94AL85000, there is a non-exclusive
 * license for use of this work by or on behalf of the U.S. Government.
 * Export of this program may require a license from the United States
 * Government. See CopyrightHistory.txt for complete details.
 * 
 */

package gov.sandia.cognition.statistics.montecarlo;

import gov.sandia.cognition.annotation.PublicationReference;
import gov.sandia.cognition.annotation.PublicationType;
import gov.sandia.cognition.evaluator.Evaluator;
import gov.sandia.cognition.util.CloneableSerializable;
import java.util.ArrayList;
import java.util.Random;

/**
 * A sampling technique based on the Monte Carlo method.
 * @param <DataType> Type of data used as inputs by the target function
 * @param <SampleType> Type of samples generated by the sampler
 * @param <FunctionType> Type of Evaluator to sample from
 * @author Kevin R. Dixon
 * @since 3.0
 */
@PublicationReference(
    author="Wikipedia",
    title="Monte Carlo method",
    type=PublicationType.WebPage,
    year=2010,
    url="http://en.wikipedia.org/wiki/Monte_carlo_method"
)
public interface MonteCarloSampler<DataType,SampleType,FunctionType extends Evaluator<? super DataType,Double>>
    extends CloneableSerializable
{

    /**
     * Draws samples according to the distribution of the target function.
     * @param targetFunction
     * Target function that we want to generate samples.
     * @param random
     * Random-number generator.
     * @param numSamples
     * Number of samples to generate.
     * @return
     * Samples
     */
    public ArrayList<? extends SampleType> sample(
        FunctionType targetFunction,
        Random random,
        int numSamples );

}