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 }