View Javadoc

1   /*
2    * Copyright 2006 - 2012 Christina Bohk and Roland Ewald
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 p3j.simulation.assignments.plugintype;
17  
18  import james.core.math.random.generators.IRandom;
19  import james.core.util.misc.Pair;
20  
21  import java.util.List;
22  import java.util.Map;
23  
24  import p3j.misc.errors.GeneratorError;
25  import p3j.pppm.IProjectionModel;
26  import p3j.pppm.parameters.ParameterAssignment;
27  import p3j.pppm.parameters.ParameterInstance;
28  
29  /**
30   * Interface for all PPPM simulators/analysers, which work on top of the
31   * calculation component. There are different ways of analysing and simulating
32   * this model, e.g. by Monte-Carlo simulation.
33   * 
34   * 
35   * Created: August 17, 2008
36   * 
37   * @author Christina Bohk
38   * @author Roland Ewald
39   * 
40   */
41  public interface IParamAssignmentGenerator {
42  
43  	/**
44  	 * Initializes generator with the projection setup.
45  	 * 
46  	 * @param projection
47  	 *          the projection setup for which a valid (i.e., complete) parameter
48  	 *          assignment shall be generated.
49  	 */
50  	void init(IProjectionModel projection);
51  
52  	/**
53  	 * This is the main execution method for PPPM simulators/analysers. mapping
54  	 * from each {@link ParameterInstance} defined in the
55  	 * {@link p3j.pppm.ProjectionModel} to one {@link ParameterAssignment} to be
56  	 * used in the calculation. Additionally, this method retrieves all
57  	 * {@link GeneratorError} objects, which is the error log of the assignment
58  	 * generation process.
59  	 * 
60  	 * 
61  	 * @param random
62  	 *          the random number generator to be used when stochastic approaches
63  	 *          are implemented
64  	 * @return tuple, first element is the mapping from each
65  	 *         {@link ParameterInstance} defined in the
66  	 *         {@link p3j.pppm.ProjectionModel} to one {@link ParameterAssignment}
67  	 *         to be used, the second element is the error log
68  	 */
69  	Pair<Map<ParameterInstance, ParameterAssignment>, List<GeneratorError>> chooseParamAssignments(
70  	    IRandom random);
71  
72  	/**
73  	 * Retrieves number of possible parameter assignments that is left and can be
74  	 * generated by the assignment generator. If this returns 0, the execution
75  	 * will stop. Note that this is the <i>minimal</i> number, i.e. it may change
76  	 * dynamically over time and may even increase from one call to another.
77  	 * 
78  	 * @return minimum number of assignments that can be generated
79  	 */
80  	long assignmentsLeft();
81  
82  }