The Objective Function

An objective function compares a model with observations given a particular set of parameters. ObjectiveFunction provides two generic objective functions that use a lookup table:

The ObjectiveFunction.ObjectiveFunctionMisfit class uses a single value which is stored directly in the lookup table; and
the ObjectiveFunction.ObjectiveFunctionResidual class uses an array containing the residuals. This array is stored in an auxiliary file.
the ObjectiveFunction.ObjectiveFunctionSimObs class uses a pandas series to store named simulated observations. The pandas series is stored as a json file.

The lookup table is queried using either the ObjectiveFunction.ObjectiveFunction.get_result() which takes a dictionary of parameter values or by calling the ObjectiveFunction instance with a numpy array containing parameter values. A lookup can have different results depending on the state of the entry in the lookup table. The methods ObjectiveFunction.ObjectiveFunction.values2params() and ObjectiveFunction.ObjectiveFunction.params2values() can be used to map between an array and a dictionary of parameter values and vice versa.

Lookup Result
call	old state	new state	result
`get_result(A)`	N/A	PROVISIONAL	raises `ObjectiveFunction.PreliminaryRun`
`get_result(A)`	PROVISIONAL	NEW	raises `ObjectiveFunction.NewRun`
`get_result(B)`	PROVISIONAL	N/A	raises `ObjectiveFunction.Waiting`, drops provisional entry
`get_result(A)`	NEW	NEW	random positive value
`get_result(A)`	ACTIVE	ACTIVE	random positive value
`get_result(A)`	COMPLETED	COMPLETED	get stored value
`get_new()`	NEW	ACTIVE	get parameter set that is in NEW state
`set_result(A, val)`	ACTIVE	COMPLETED	get parameter set that is in NEW state

The system can automatically determine if models can be run in parallel. When the optimiser is called entries with the NEW or ACTIVE state return a random value. The first time a parameter set, A, lookup fails it is added with the PROVISIONAL state. If when the optimiser is run again the same parameter set A is requested the entry enters the NEW state and a ObjectiveFunction.NewRun exception is raised. If however a different parameter set B is requested the PROVISIONAL parameter is dropped from the lookup table and a ObjectiveFunction.Waiting exception is raised. A different parameter set B indicates that the parameter set depends on the not yet know values and the optimiser has to wait until they become available before trying again.

The ObjectiveFunction.ObjectiveFunction.get_new() method is used to get a parameter set that is in the NEW state. The entry is moved into the ACTIVE state. A RuntimeError exception is raised if there is no parameter set in the NEW state.

Finally, the result of the objective function for a particular parameter set is set using the ObjectiveFunction.ObjectiveFunction.set_result(). A LookupError is raised if there is no entry with that parameter set. A RuntimeError exception is raised if the entry is not in the ACTIVE state unless forced. On success the entry moves to the COMPLETED state.