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.model;
17
18 import broadwick.BroadwickException;
19 import broadwick.config.generated.Parameter;
20 import broadwick.config.generated.Prior;
21 import broadwick.config.generated.UniformPrior;
22 import broadwick.data.Lookup;
23 import com.google.common.base.Predicate;
24 import com.google.common.collect.Iterables;
25 import java.util.ArrayList;
26 import java.util.List;
27 import lombok.Getter;
28 import lombok.extern.slf4j.Slf4j;
29
30 /**
31 * This interface declares a model for the Broadwick framework. To create a model for this framework (by model we mean
32 * both the model and the methodology for running/solving it) the user creates an implementation of this class and
33 * refers to it in the framework configuration file. <code>
34 * public class SIRModel implements Model {
35 * public void run() {
36 * // perform model specific step here
37 * }
38 *
39 * @Parameter(hint="transmission term")
40 * public double beta;
41 * }
42 * </code>
43 */
44 @Slf4j
45 public abstract class Model {
46
47 /**
48 * Set the xml string for the <model> element in the configuration file.
49 * @param model a string representation of the xml section defining the configuration of the model.
50 */
51 public final void setModelConfiguration(final String model) {
52 this.model = model;
53 this.priors = new ArrayList<>();
54 }
55
56 /**
57 * Set the lookup object that allows access to the data files specified in the configuration file.
58 * @param lookup the XML element corresponding to the Model element in the config.
59 */
60 public final void setModelDataLookup(final Lookup lookup) {
61 this.lookup = lookup;
62 }
63
64 /**
65 * Set the list of parameters for the model.
66 * @param parameters a collection of parameters for the model.
67 */
68 public final void setModelParameters(final List<Parameter> parameters) {
69 this.parameters = parameters;
70 }
71
72 /**
73 * Set the list of priors for the model.
74 * @param priors a collection of priors for the model.
75 */
76 public final void setModelPriors(final List<Prior> priors) {
77 this.priors.addAll(priors);
78 }
79
80 /**
81 * Get the prior of a paramter for the model given the parameter name (as defined in the config file).
82 * @param name the name of the parameter.
83 * @return the prior defeind in the configuration file.
84 */
85 public final UniformPrior getUniformPrior(final String name) {
86 return (UniformPrior) Iterables.find(priors, new Predicate<Prior>() {
87 @Override
88 public boolean apply(final Prior prior) {
89 return name.equals(prior.getId());
90 }
91 });
92 }
93
94 /**
95 * Determine whether or not a parameter exists in the config file.
96 * @param name the name of the parameter.
97 * @return true if the parameter exists in the config file, false otherwise.
98 */
99 public final boolean hasParameter(final String name) {
100 return Iterables.tryFind(parameters, new Predicate<Parameter>() {
101 @Override
102 public boolean apply(final Parameter parameter) {
103 return name.equals(parameter.getId());
104 }
105 }).isPresent();
106 }
107
108 /**
109 * Get the value of a parameter for the model given the parameter name (as defined in the config file).
110 * @param name the name of the parameter.
111 * @return a string value of the value for the parameter.
112 */
113 public final String getParameterValue(final String name) {
114 try {
115 return Iterables.find(parameters, new Predicate<Parameter>() {
116 @Override
117 public boolean apply(final Parameter parameter) {
118 return name.equals(parameter.getId());
119 }
120 }).getValue();
121 } catch (java.util.NoSuchElementException e) {
122 log.error("{} in is not configured for the model.", name);
123 throw new BroadwickException(String.format("Could not find parameter %s in configuration file.", name));
124 }
125 }
126
127 /**
128 * Get the value (as a double) of a parameter for the model given the parameter name (as defined in the config
129 * file).
130 * @param name the name of the parameter.
131 * @return a string value of the value for the parameter.
132 */
133 public final Double getParameterValueAsDouble(final String name) {
134 return Double.parseDouble(getParameterValue(name));
135 }
136
137 /**
138 * Get the value (as an integer) of a parameter for the model given the parameter name (as defined in the config
139 * file).
140 * @param name the name of the parameter.
141 * @return a string value of the value for the parameter.
142 */
143 public final Integer getParameterValueAsInteger(final String name) {
144 return Integer.parseInt(getParameterValue(name));
145 }
146
147 /**
148 * Get the value (as a boolean) of a parameter for the model given the parameter name (as defined in the config
149 * file).
150 * @param name the name of the parameter.
151 * @return a string value of the value for the parameter.
152 */
153 public final Boolean getParameterValueAsBoolean(final String name) {
154 return Boolean.parseBoolean(getParameterValue(name));
155 }
156
157 /**
158 * Initialise the model. This method is called by the framework before calling the models run method to allow the
159 * implementation of the model to perform any initialisation required.
160 */
161 public abstract void init();
162
163 /**
164 * Run the model. This is the entry point to the model from the framework, up til now the framework has read any
165 * configuration files and processed data mentioned therein.
166 */
167 public abstract void run();
168
169 /**
170 * End the model. This method is called by the framework after the model has finished running.
171 */
172 public abstract void finalise();
173 @Getter
174 @SuppressWarnings("PMD.UnusedPrivateField")
175 private String model;
176 @SuppressWarnings("PMD.UnusedPrivateField")
177 @Getter
178 private Lookup lookup;
179 @SuppressWarnings("PMD.UnusedPrivateField")
180 @Getter
181 private List<Parameter> parameters;
182 @SuppressWarnings("PMD.UnusedPrivateField")
183 @Getter
184 private List<Prior> priors;
185 }