1 /*
2 * Copyright 2013 University of Glasgow.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package broadwick.montecarlo;
17
18 import broadwick.statistics.Samples;
19
20 /**
21 * This interface encapsulates the results from a Monte Carlo run. By Default a Monte Carlo object will run simulations
22 * and use implementations of this class to store the results. It does do by adding the simulation results to the
23 * Samples object that is used to obtain an expected value for the simulation.
24 */
25 public interface MonteCarloResults {
26
27 /**
28 * Get the score for the Monte Carlo simulation. The Acceptor interface and it's implementing classes require a
29 * known value in this class for their analysis, e.g. this method may return the likelihood of the simulation and
30 * the Acceptor class (e.g. MetropolisHastingsAcceptor) will use the McResults.getExpectedValue() method to
31 * determine whether or not to accept this proposed step.
32 * @return the value of the score.
33 */
34 double getExpectedValue();
35
36 /**
37 * Get the results of the Monte Carlo simulations as a Samples object.
38 * @return A samples object that contains the results of each Monte Carlo Simulation.
39 */
40 Samples getSamples();
41
42 /**
43 * Get a CSV string of the Monte Carlo results stored in this class. This will be used for logging and for output to
44 * file and can contain statistics about the results e.g. the mean, std deviation etc. as appropriate.
45 * @return a CSV representation of the results.
46 */
47 String toCsv();
48
49 /**
50 * Join another Monte Carlo results object to this one. When running a Monte Carlo simulation it is often necessary
51 * to append the results from a simulation to a 'master' results object.
52 * @param results the results object to join.
53 * @return the new/updated results object.
54 */
55 MonteCarloResults join(MonteCarloResults results);
56
57 /**
58 * Clear the results of the MonteCarloResults object. This will be called by several algorithms (e.g. MCMC) to
59 * clear any cached results that should be cleared between runs.
60 */
61 void reset();
62
63 }