ObjectiveFunction API

class ObjectiveFunction.LookupState(value)

the state of the parameter set

  • PROVISIONAL: new entry under consideration

  • NEW: new parameter set

  • CONFIGURING: the model run is being configured

  • CONFIGURED: the model run has been configured

  • ACTIVE: parameter set being computed

  • RUN: the model has run

  • POSTPROCESSING: the model results are being post-processed

  • COMPLETED: completed parameter set

exception ObjectiveFunction.NewRun

Exception used when a new entry in the lookup table was created

exception ObjectiveFunction.NoNewRun

Exception used to indicate that no new runs to be computed

class ObjectiveFunction.ObjFunConfig(fname: pathlib.Path)

handle ObjectiveFunction configuration

Parameters

fname (Path) – the name of the configuration file

property basedir

the base directory

property cfg

a dictionary containing the configuration

property objectiveFunction

intantiate a ObjectiveFunction object from config object

property objfunType

the objective function type

property observationNames

the name of the observations

property optimise_parameters

a dictionary of parameters that should be optimised

property parameters

a dictionary of parameters

property scenario

the name of the scenario

property study

the name of the study

property values

a dictionary of the parameter values

class ObjectiveFunction.ObjectiveFunction(study: str, basedir: pathlib.Path, parameters: Mapping[str, ObjectiveFunction.parameter.Parameter], scenario=None, db=None, prelim=True)

class maintaining a lookup table for an objective function

Parameters

  • study (str) – the name of the study

  • basedir (Path) – the directory in which the lookup table is kept

  • parameters – a dictionary mapping parameter names to the range of permissible parameter values

  • scenario (str) – name of the default scenario

  • db (str) – database connection string

  • prelim (bool) – when True failed parameter look up raises a PreliminaryRun exception otherwise a NewRun exception is raised. Default=True

__call__(x, grad)

look up parameters

Parameters

  • x – vector containing parameter values

  • grad (numpy.ndarray) – vector of length 0

Raises

  • NewRun – when lookup fails

  • Waiting – when completed entries are required

Returns

returns the value if lookup succeeds and state is completed return a random value otherwise

Return type

float

property active_parameters

the constant parameters

property basedir

the basedirectory

property constant_parameters

the constant parameters

getLowerBounds()

an array containing the lower bounds

getRunID(parameters, scenario=None)

get ID of run

Parameters

  • parms – dictionary containing parameter values

  • scenario – the name of the scenario

getScenario(scenario=None)

get scenario object

Parameters

scenario (str) – the name of the scenario or None if None get the default scenario

getState(runid)

get the state of a run with ID

Parameters

runid – ID of ru

Returns

state of run

getUpperBounds()

an array containing the upper bounds

get_new(scenario=None, with_id=False)

get a set of parameters that are not yet processed

Parameters

  • scenario – the name of the scenario

  • with_id – when set to True also return run ID

The parameter set changes set from new to active

Returns

dictionary of parameter values for which to compute the model

Raises

NoNewRun – if there is no new parameter set

abstract get_result(params, scenario=None)

look up parameters

Parameters

  • parms – dictionary containing parameter values

  • scenario – the name of the scenario

Raises

  • NewRun – when lookup fails

  • Waiting – when completed entries are required

Returns

returns the value if lookup succeeds and state is completed return a random value otherwise

get_with_state(state, scenario=None, with_id=False, new_state=None)

get a set of parameters in a particular state

Parameters

  • state – find run in state

  • scenario – the name of the scenario

  • with_id – when set to True also return run ID

  • new_state – when not None set the state of the run to new_state

Get a set of parameters for a run in a particular state. Optionally the run transitions to new_state.

Returns

dictionary of parameter values for which to compute the model

Raises

LookupError – if there is no parameter set in specified state

property lower_bounds

an array containing the lower bounds

property num_active_params

the number of parameters

property num_params

the number of parameters

property parameters

dictionary of parameters

params2values(params, include_constant=True)

create an array of values from a dictionary of parameters :param params: a dictionary of parameters :param include_constant: set to False to exclude constant parameters :return: a array of values

property scenarios

the list of scenario names associated with study

setDefaultScenario(name)

set the default scenario

Parameters

name (str) – name of scenario

setState(runid, state)

set the state of run

Parameters

  • runid – ID of run

  • state – the new state

abstract set_result(params, result, scenario=None, force=False)

set the result for a paricular parameter set

Parameters

  • parms – dictionary of parameters

  • result – result value to set

  • scenario – the name of the scenario

  • force – force setting results irrespective of state

state(parameters, scenario=None)

get run state

Parameters

  • parms – dictionary containing parameter values

  • scenario – the name of the scenario

property study

the name of the study

property upper_bounds

an array containing the upper bounds

values2params(values)

create a dictionary of parameter values from list of values :param values: a list/tuple of values :return: a dictionary of parameters

class ObjectiveFunction.ObjectiveFunctionMisfit(study: str, basedir: pathlib.Path, parameters: Mapping[str, ObjectiveFunction.parameter.Parameter], scenario=None, db=None, prelim=True)

class maintaining a lookup table for an objective function

store the model misfit in the database

Parameters

  • study (str) – the name of the study

  • basedir (Path) – the directory in which the lookup table is kept

  • parameters – a dictionary mapping parameter names to the range of permissible parameter values

  • scenario (str) – name of the default scenario

  • db (str) – database connection string

  • prelim (bool) – when True failed parameter look up raises a PreliminaryRun exception otherwise a NewRun exception is raised. Default=True

get_result(params, scenario=None)

look up parameters

Parameters

  • parms – dictionary containing parameter values

  • scenario – the name of the scenario

Raises

  • NewRun – when lookup fails

  • Waiting – when completed entries are required

Returns

returns the value if lookup succeeds and state is completed return a random value otherwise

Return type

float

set_result(params, result, scenario=None, force=False)

set the result for a paricular parameter set

Parameters

  • parms – dictionary of parameters

  • result (float) – result value to set

  • scenario – the name of the scenario

  • force – force setting results irrespective of state

class ObjectiveFunction.ObjectiveFunctionResidual(study: str, basedir: pathlib.Path, parameters: Mapping[str, ObjectiveFunction.parameter.Parameter], scenario=None, db=None, prelim=True)

class maintaining a lookup table for an objective function

store the name of a file containing the residuals

Parameters

  • study (str) – the name of the study

  • basedir (Path) – the directory in which the lookup table is kept

  • parameters – a dictionary mapping parameter names to the range of permissible parameter values

  • scenario (str) – name of the default scenario

  • db (str) – database connection string

  • prelim (bool) – when True failed parameter look up raises a PreliminaryRun exception otherwise a NewRun exception is raised. Default=True

get_result(params, scenario=None)

look up parameters

Parameters

  • parms – dictionary containing parameter values

  • scenario – the name of the scenario

Raises

  • NewRun – when lookup fails

  • Waiting – when completed entries are required

Returns

returns the value if lookup succeeds and state is completed return a random value otherwise

Return type

numpy.arraynd

property num_residuals

the number of residuals

set_result(params, result, scenario=None, force=False)

set the result for a paricular parameter set

Parameters

  • parms – dictionary of parameters

  • result (numpy.ndarray) – residuals to store

  • scenario – the name of the scenario

  • force – force setting results irrespective of state

class ObjectiveFunction.ObjectiveFunctionSimObs(study: str, basedir: pathlib.Path, parameters: Mapping[str, ObjectiveFunction.parameter.Parameter], observationNames: Sequence[str], scenario=None, db=None, prelim=True)

class maintaining a lookup table for an objective function

store the name of a file containing the residuals

Parameters

  • study (str) – the name of the study

  • basedir (Path) – the directory in which the lookup table is kept

  • parameters – a dictionary mapping parameter names to the range of permissible parameter values

  • observationNames – a list of observation names

  • scenario (str) – name of the default scenario

  • db (str) – database connection string

  • prelim (bool) – when True failed parameter look up raises a PreliminaryRun exception otherwise a NewRun exception is raised. Default=True

get_result(params, scenario=None)

look up parameters

Parameters

  • parms – dictionary containing parameter values

  • scenario – the name of the scenario

Raises

  • NewRun – when lookup fails

  • Waiting – when completed entries are required

Returns

returns the value if lookup succeeds and state is completed return a random value otherwise

Return type

numpy.arraynd

get_simobs(params, scenario=None)

look up parameters

Parameters

  • parms – dictionary containing parameter values

  • scenario – the name of the scenario

Raises

  • NewRun – when lookup fails

  • Waiting – when completed entries are required

Returns

returns simulated observations if lookup succeeded or a random pandas Series

Return type

pandas.Series

property num_residuals

the number of residuals

set_result(params, result, scenario=None, force=False)

set the result for a paricular parameter set

Parameters

  • parms – dictionary of parameters

  • result (numpy.ndarray) – residuals to store

  • scenario – the name of the scenario

  • force – force setting results irrespective of state

class ObjectiveFunction.Parameter(value: ObjectiveFunction.parameter.T, minv: ObjectiveFunction.parameter.T, maxv: ObjectiveFunction.parameter.T, constant: bool = False)

a parameter with minimum and maximum value

Parameters

  • value – the value

  • minv – minimum value (inclusive)

  • maxv – maximum value (inclusive)

  • constant (bool) – set to True to exclude parameter from optimisation

__call__(value: ObjectiveFunction.parameter.T) → ObjectiveFunction.parameter.T

check the value is within the bounds and apply any rounding

property constant: bool

whether the parameter should be excluded from optimisation

abstract inv_transform(dbval: int) → ObjectiveFunction.parameter.T

transform from the internal storage format

property maxv: ObjectiveFunction.parameter.T

the maximum value the parameter can take

property minv: ObjectiveFunction.parameter.T

the minimum value the parameter can take

abstract transform(value: ObjectiveFunction.parameter.T) → int

transform the value to the internal storage format

property value: ObjectiveFunction.parameter.T

the parameter value

class ObjectiveFunction.ParameterFloat(value: float, minv: float, maxv: float, resolution: float = 1e-06, constant: bool = False)

a float parameter with minimum and maximum value

Parameters

  • value (float) – the value

  • minv (float) – minimum value (inclusive)

  • maxv (float) – maximum value (inclusive)

  • resolution (float) – resolution, by default 1e-6

  • constant (bool) – set to True to exclude parameter from optimisation

inv_transform(dbval: int) → float

transform from the internal storage format

property resolution: float

the resolution used when converting between integer and floats

transform(value: float) → int

transform the value to the internal storage format

class ObjectiveFunction.ParameterInt(value: int, minv: int, maxv: int, constant: bool = False)

a integer parameter with minimum and maximum value

Parameters

  • value (int) – the value

  • minv (int) – minimum value (inclusive)

  • maxv (int) – maximum value (inclusive)

  • constant (bool) – set to True to exclude parameter from optimisation

inv_transform(dbval: int) → int

transform from the internal storage format

transform(value: int) → int

transform the value to the internal storage format

exception ObjectiveFunction.PreliminaryRun

Exception used when a preliminary entry in the lookup table was created

exception ObjectiveFunction.Waiting

Exception used to indicate that entries need to be completed