apsis.models package

Submodules

apsis.models.candidate module

class apsis.models.candidate.Candidate(params, worker_information=None)

Bases: object

A Candidate is a dictionary of parameter values, which should - or have been - evaluated.

A Candidate object can be seen as a single iteration of the experiment. It is first generated as a suggestion of which parameter set to evaluate next, then updated with the result and cost of the evaluation.

Attributes

Methods

cost = None

params = None

result = None

to_csv_entry(delimiter=', ', key_order=None)

Returns a csv entry representing this candidate.

It is delimited by delimiter, and first consists of all parameters in the order defined by key_order, followed by the cost and result.

Parameters:

delimiter : string, optional

The string delimiting csv entries

key_order : list of param names, optional

A list defining the order of keys written to csv. If None, the order will be set by sorting the keys.

Returns:

string : string

The (one-line) string representing this Candidate as a csv line

to_dict()

EXPERIMENTAL

worker_information = None

apsis.models.candidate.from_dict(dict)

EXPERIMENTAL

apsis.models.experiment module

class apsis.models.experiment.Experiment(name, parameter_definitions, minimization_problem=True)

Bases: object

An Experiment is a set of parameter definitions and multiple candidate evaluations thereon.

Attributes

Methods

add_finished(candidate)

Announces a Candidate instance to be finished evaluating.

This moves the Candidate instance to the candidates_finished list and updates the best_candidate.

Parameters:

candidate : Candidate

The Candidate to be added to the finished list.

Raises:

ValueError : :

Iff candidate is not a Candidate object.

add_pausing(candidate)

Updates the experiment that work on candidate has been paused.

This updates candidates_pending list and the candidates_working list if it contains the candidate.

Parameters:

candidate : Candidate

The Candidate instance that is currently paused.

Raises:

ValueError : :

Iff candidate is no Candidate object.

add_pending(candidate)

Adds a new pending Candidate object to be evaluated.

This function should be used when a new pending candidate is supposed to be evaluated. If an old Candidate should be updated as just pausing, use the add_pausing function.

Parameters:

candidate : Candidate

The Candidate instance that is supposed to be evaluated soon.

Raises:

ValueError : :

Iff candidate is no Candidate object.

add_working(candidate)

Updates the experiment to now start working on candidate.

This updates candidates_working list and the candidates_pending list if candidate is in the candidates_pending list.

Parameters:

candidate : Candidate

The Candidate instance that is currently being worked on.

Raises:

ValueError : :

Iff candidate is no Candidate object.

best_candidate = None

better_cand(candidateA, candidateB)

Determines whether CandidateA is better than candidateB in the context of this experiment. This is done as follows: If candidateA’s result is None, it is not better. If candidateB’s result is None, it is better. If it is a minimization problem and the result is smaller than B’s, it is better. Corresponding for being a maximization problem.

Parameters:

candidateA : Candidate

The candidate which should be better.

candidateB : Candidate

The baseline candidate.

Returns:

result : bool

True iff A is better than B.

Raises:

ValueError : :

If candidateA or candidateB are no Candidates.

candidates_finished = None

candidates_pending = None

candidates_working = None

clone()

Create a deep copy of this experiment and return it.

Returns:

copied_experiment : Experiment

A deep copy of this experiment.

minimization_problem = None

name = None

parameter_definitions = None

to_csv_results(delimiter=', ', line_delimiter='\n', key_order=None, wHeader=True, fromIndex=0)

Generates a csv result string from this experiment.

Parameters:

delimiter : string, optional

The column delimiter

line_delimiter : string, optional

The line delimiter

key_order : list of strings, optional

The order in which the parameters should be written. If None, the order is defined by sorting the parameter names.

wHeader : bool, optional

Whether a header should be written. Defaults to true.

from_index : int, optional

Beginning from which result the csv should be generated.

Returns:

csv_string : string

The corresponding csv string

steps_included : int

The number of steps included in the csv.

warp_pt_in(params)

Warps in a point.

Parameters:

params : dict of string keys

The point to warp in

Returns:

warped_in : dict of string keys

The warped-in parameters.

warp_pt_out(params)

Warps out a point.

Parameters:

params : dict of string keys

The point to warp out

Returns:

warped_out : dict of string keys

The warped-out parameters.

apsis.models.parameter_definition module

class apsis.models.parameter_definition.AsymptoticNumericParamDef(asymptotic_border, border)

Bases: apsis.models.parameter_definition.NumericParamDef

This represents an asymptotic parameter definition.

It consists of a fixed border - represented at 0 - and an asymptotic border - represented at 1.

In general, multiplying the input parameter by 1/10th means a multiplication of the warped-in value by 1/2. This means that each interval between 10^-i and 10^-(i-1) is represented by an interval of length 1/2^i on the hypercube.

For example, assume that you want to optimize over a learning rate. Generally, they are close to 0, with parameter values (and therefore possible optimization values) like 10^-1, 10^-4 or 10^-6. This could be done by initializing this class with asymptotic_border = 0 and border = 1.

Trying to optimize a learning rate decay - which normally is close to 1 - one could initialize this class with asymptotic_border = 1 and border = 0.

Attributes

Methods

asymptotic_border = None

border = None

warp_in(value_in)

Warps value_in in.

Parameters:

value_in : float

Should be between (including) border and asymptotic_border. If outside the corresponding interval, it is automatically translated to 0 and 1 respectively.

Returns:

value_in : float

The [0, 1]-translated value.

warp_out(value_out)

Warps value_in out.

Parameters:

value_out : float

Should be between (including) 0 and 1. If bigger than 1, it is translated to border. If smaller than 0, it is translated to asymptotic_border.

Returns:

value_out : float

The translated value.

class apsis.models.parameter_definition.ComparableParamDef

Bases: object

This class defines an ordinal parameter definition subclass, that is a

parameter definition in which the values are comparable.

It additionally implements the compare_values_function.

Methods

compare_values(one, two)

Compare values one and two of this datatype.

It has to follow the same return semantics as the Python standard __cmp__ methods, meaning it returns negative integer if one < two, zero if one == two, a positive integer if one > two.

Parameters:

one : object in parameter definition

The first value used in comparison.

two : object in parameter definition

The second value used in comparison.

Returns:

comp: integer :

comp < 0 iff one < two. comp = 0 iff one = two. comp > 0 iff one > two.

class apsis.models.parameter_definition.FixedValueParamDef(values)

Bases: apsis.models.parameter_definition.PositionParamDef

Extension of PositionParamDef, in which the position is equal to the value of each entry from values.

Attributes

Methods

class apsis.models.parameter_definition.MinMaxNumericParamDef(lower_bound, upper_bound)

Bases: apsis.models.parameter_definition.NumericParamDef

Defines a numeric parameter definition defined by a lower and upper bound.

Attributes

Methods

is_in_parameter_domain(value)

warp_in(value_in)

warp_out(value_out)

x_max = None

x_min = None

class apsis.models.parameter_definition.NominalParamDef(values)

Bases: apsis.models.parameter_definition.ParamDef

This defines a nominal parameter definition.

A nominal parameter definition is defined by the values as given in the init function. These are a list of possible values it can take.

Attributes

Methods

is_in_parameter_domain(value)

Tests whether value is in self.values as defined during the init function.

values = None

class apsis.models.parameter_definition.NumericParamDef(warping_in, warping_out)

Bases: apsis.models.parameter_definition.ParamDef, apsis.models.parameter_definition.ComparableParamDef

This class defines a numeric parameter definition.

It is characterized through the existence of a warp_in and a warp_out function. The warp_in function squishes the whole parameter space to the unit space [0, 1], while the warp_out function reverses this. Note that it is necessary that

x = warp_in(warp_out(x)) for x in [0, 1] and x = warp_out(warp_in(x)) for x in allowed parameter space.

Attributes

Methods

compare_values(one, two)

distance(valueA, valueB)

is_in_parameter_domain(value)

Uses the warp_out function for tests.

warp_in(value_in)

Warps value_in into the [0, 1] space.

Parameters:

value_in : float

The input value

Returns:

value_in_scaled: float in [0, 1] :

The scaled output value.

warp_out(value_out)

Warps value_out out of the [0, 1] space.

Parameters:

value_out : float in [0, 1]

The output value.

Returns:

value_out_unscaled : float

The unscaled value in the parameter space.

warping_in = None

warping_out = None

class apsis.models.parameter_definition.OrdinalParamDef(values)

Bases: apsis.models.parameter_definition.NominalParamDef, apsis.models.parameter_definition.ComparableParamDef

Defines an ordinal parameter definition.

This class inherits from NominalParamDef and ComparableParameterDef, and consists of basically a list of possible values with a defined order. This defined order is simply the order in which the elements are in the list.

Attributes

Methods

compare_values(one, two)

Compare values of this ordinal data type. Return is the same semantic as in __cmp__.

Comparison takes place based on the index the given values one and two have in the values list in this object. Meaning if this ordinal parameter definition has a values list of [3,5,1,4]’, then ‘5’ will be considered smaller than ‘1’ and ‘1’ bigger than ‘5’ because the index of ‘1’ in this list is higher than the index of ‘5’.

distance(valueA, valueB)

This distance is defined as the absolute difference between the values’ position in the list, normed to the [0, 1] hypercube.

class apsis.models.parameter_definition.ParamDef

Bases: object

This represents the base class for a parameter definition.

Every member of this class has to implement at least the is_in_parameter_domain method to check whether objects are in the parameter domain.

Methods

distance(valueA, valueB)

Returns the distance between valueA and valueB. In this case, it’s 0 iff valueA == valueB, 1 otherwise.

is_in_parameter_domain(value)

Should test whether a certain value is in the parameter domain as defined by this class.

Parameters:

value : object

Tests whether the object is in the parameter domain.

Returns:

is_in_parameter_domain : bool

True iff value is in the parameter domain as defined by this instance.

class apsis.models.parameter_definition.PositionParamDef(values, positions)

Bases: apsis.models.parameter_definition.OrdinalParamDef

Defines positions for each of its values.

Attributes

Methods

distance(valueA, valueB)

positions = None

warp_in(value_in)

Warps in the value to a [0, 1] hypercube value.

warp_out(value_out)

Warps out a value from a [0, 1] hypercube to one of the values.

Module contents