API Documentation

deep_architect.core

class deep_architect.core.Addressable(scope, name)[source]

Bases: object

Base class for classes whose objects have to be registered in a scope.

Provides functionality to register objects in a scope.

Parameters:
  • scope (deep_architect.core.Scope) – Scope object where the addressable object will be registered.
  • name (str) – Unique name used to register the addressable object.
_get_base_name()[source]

Get the class name.

Useful to create unique names for an addressable object.

Returns:Class name.
Return type:str
get_name()[source]

Get the name with which the object was registered in the scope.

Returns:Unique name used to register the object.
Return type:str
class deep_architect.core.DependentHyperparameter(fn, hyperps, scope=None, name=None)[source]

Bases: deep_architect.core.Hyperparameter

Hyperparameter that depends on other hyperparameters.

The value of a dependent hyperparameter is set by a calling a function using the values of the dependent hyperparameters as arguments. This hyperparameter is convenient when we want to express search spaces where the values of some hyperparameters are computed as a function of the values of some other hyperparameters, rather than set independently.

Parameters:
  • fn (dict[str, object] -> object) – Function used to compute the value of the hyperparameter based on the values of the dependent hyperparameters.
  • hyperps (dict[str, deep_architect.core.Hyperparameter]) – Dictionary mapping names to hyperparameters. The names used in the dictionary should correspond to the names of the arguments of fn.
  • scope (deep_architect.core.Scope, optional) – The scope in which to register the hyperparameter in.
  • name (str, optional) – Name from which the name of the hyperparameter in the scope is derived.
_update()[source]

Checks if the hyperparameter is ready to be set, and sets it if that is the case.

class deep_architect.core.Hyperparameter(scope=None, name=None)[source]

Bases: deep_architect.core.Addressable

Base hyperparameter class.

Specific hyperparameter types are created by inheriting from this class. Hyperparameters keep references to the modules that are dependent on them.

Note

Hyperparameters with easily serializable values are preferred due to the interaction with the search logging and multi-GPU functionalities. Typical valid serializable types are integers, floats, strings. Lists and dictionaries of serializable types are also valid.

Parameters:
  • scope (deep_architect.core.Scope, optional) – Scope in which the hyperparameter will be registered. If none is given, uses the default scope.
  • name (str, optional) – Name used to derive an unique name for the hyperparameter. If none is given, uses the class name to derive the name.
_check_value(val)[source]

Checks if the value is valid for the hyperparameter.

When set_val is called, this function is called to verify the validity of val. This function is useful for error checking.

_register_dependent_hyperparameter(hyperp)[source]

Registers an hyperparameter as being dependent on this hyperparameter.

Parameters:module (deep_architect.core.Hyperparameter) – Hyperparameter dependent of this hyperparameter.
_register_module(module)[source]

Registers a module as being dependent of this hyperparameter.

Parameters:module (deep_architect.core.Module) – Module dependent of this hyperparameter.
assign_value(val)[source]

Assigns a value to the hyperparameter.

The hyperparameter value must be valid for the hyperparameter in question. The hyperparameter becomes set if the call is successful.

Parameters:val (object) – Value to assign to the hyperparameter.
get_value()[source]

Get the value assigned to the hyperparameter.

The hyperparameter must have already been assigned a value, otherwise asserts False.

Returns:Value assigned to the hyperparameter.
Return type:object
has_value_assigned()[source]

Checks if the hyperparameter has been assigned a value.

Returns:True if the hyperparameter has been assigned a value.
Return type:bool
class deep_architect.core.Input(module, scope, name)[source]

Bases: deep_architect.core.Addressable

Manages input connections.

Inputs may be connected to a single output. Inputs and outputs are associated to a single module.

See also: deep_architect.core.Output and deep_architect.core.Module.

Parameters:
connect(from_output)[source]

Connect an output to this input.

Changes the state of both the input and the output. Asserts False if the input is already connected.

Parameters:from_output (deep_architect.core.Output) – Output to connect to this input.
disconnect()[source]

Disconnects the input from the output it is connected to.

Changes the state of both the input and the output. Asserts False if the input is not connected.

get_connected_output()[source]

Get the output to which the input is connected to.

Returns:Output to which the input is connected to.
Return type:deep_architect.core.Output
get_module()[source]

Get the module with which the input is associated with.

Returns:Module with which the input is associated with.
Return type:deep_architect.core.Module
is_connected()[source]

Checks if the input is connected.

Returns:True if the input is connected.
Return type:bool
reroute_connected_output(to_input)[source]

Disconnects the input from the output it is connected to and connects the output to a new input, leaving this input in a disconnected state.

Changes the state of both this input, the other input, and the output to which this input is connected to.

Note

Rerouting operations are widely used in deep_architect.modules.SubstitutionModule. See also: deep_architect.core.Output.reroute_all_connected_inputs().

Parameters:to_input (deep_architect.core.Input) – Input to which the output is going to be connected to.
class deep_architect.core.Module(scope=None, name=None)[source]

Bases: deep_architect.core.Addressable

Modules inputs and outputs, and depend on hyperparameters.

Modules are some of the main components used to define search spaces. The inputs, outputs, and hyperparameters have names local to the module. These names are different than the ones used in the scope in which these objects are registered in.

Search spaces based on modules are very general. They can be used across deep learning frameworks, and even for purposes that do not involve deep learning, e.g., searching over scikit-learn pipelines. The main operations to understand are compile and forward.

Parameters:
  • scope (deep_architect.core.Scope, optional) – Scope object where the module is going to be registered in.
  • name (str, optional) – Unique name with which to register the module.
_compile()[source]

Compile operation for the module.

Called once when all the hyperparameters that the module depends on, and the other hyperparameters of the search space are specified. See also: _forward().

_forward()[source]

Forward operation for the module.

Called once the compile operation has been called. See also: _compile().

_get_hyperp_values()[source]

Get the values of the hyperparameters.

Returns:Dictionary of local hyperparameter names to their corresponding values.
Return type:dict[str, object]
_get_input_values()[source]

Get the values associated to the inputs of the module.

This function is used to implement forward. See also: _set_output_values() and forward().

Returns:Dictionary of local input names to their corresponding values.
Return type:dict[str, object]
_register(input_names, output_names, name_to_hyperp)[source]

Registers inputs, outputs, and hyperparameters locally for the module.

This function is convenient to avoid code repetition when registering multiple inputs, outputs, and hyperparameters.

Parameters:
_register_hyperparameter(name, h)[source]

Registers an hyperparameter that the module depends on.

Parameters:
_register_input(name)[source]

Creates a new input with the chosen local name.

Parameters:name (str) – Local name given to the input.
_register_output(name)[source]

Creates a new output with the chosen local name.

Parameters:name (str) – Local name given to the output.
_set_output_values(output_name_to_val)[source]

Set the values of the outputs of the module.

This function is used to implement forward. See also: _get_input_values() and forward().

Parameters:output_name_to_val (dict[str, object]) – Dictionary of local output names to the corresponding values to assign to those outputs.
_update()[source]

Called when an hyperparameter that the module depends on is set.

forward()[source]

The forward computation done by the module is decomposed into _compile() and _forward().

Compile can be thought as creating the parameters of the module (done once). Forward can be thought as using the parameters of the module to do the specific computation implemented by the module on some specific data (done multiple times).

This function can only called after the module and the other modules in the search space are fully specified. See also: forward().

get_hyperps()[source]
Returns:Dictionary of local hyperparameter names to the corresponding hyperparameter objects.
Return type:dict[str, deep_architect.core.Hyperparameter]
get_io()[source]
Returns:Pair with dictionaries mapping the local input and output names to their corresponding input and output objects.
Return type:(dict[str,deep_architect.core.Input], dict[str,deep_architect.core.Output])
class deep_architect.core.OrderedSet[source]

Bases: object

add(x)[source]
update(xs)[source]
class deep_architect.core.Output(module, scope, name)[source]

Bases: deep_architect.core.Addressable

Manages output connections.

Outputs may be connected to multiple inputs. Inputs and outputs are associated to a single module.

See also: deep_architect.core.Input and deep_architect.core.Module.

Parameters:
connect(to_input)[source]

Connect an additional input to this output.

Changes the state of both the input and the output.

Parameters:to_input (deep_architect.core.Input) – Input to connect to this output.
disconnect_all()[source]

Disconnects all the inputs connected to this output.

Changes the state of the output and all the inputs connected to it.

get_connected_inputs()[source]

Get the list of inputs to which is the output is connected to.

Returns:
List of the inputs to which the
output is connect to.
Return type:list[deep_architect.core.Input]
get_module()[source]

Get the module object with which the output is associated with.

Returns:
Module object with which the output is
associated with.
Return type:deep_architect.core.Module
is_connected()[source]

Checks if the output is connected.

Returns:True if the output is connected.
Return type:bool
reroute_all_connected_inputs(from_output)[source]

Reroutes all the inputs to which the output is connected to a different output.

Note

Rerouting operations are widely used in deep_architect.modules.SubstitutionModule. See also: deep_architect.core.Input.reroute_connected_output().

Parameters:from_output (deep_architect.core.Output) – Output to which the connected inputs are going to be rerouted to.
class deep_architect.core.Scope[source]

Bases: object

A scope is used to help assign unique readable names to addressable objects.

A scope keeps references to modules, hyperparameters, inputs, and outputs.

default_scope = <deep_architect.core.Scope object>
get_elem(name)[source]

Get the object that is registered in the scope with the desired name.

The name must exist in the scope.

Parameters:name (str) – Name of the addressable object registered in the scope.
Returns:Addressable object with the corresponding name.
Return type:str
get_name(elem)[source]

Get the name of the addressable object registered in the scope.

The object must exist in the scope.

Parameters:elem (deep_architect.core.Addressable) – Addressable object registered in the scope.
Returns:Name with which the object was registered in the scope.
Return type:str
get_unused_name(prefix)[source]

Creates a unique name by adding a numbered suffix to the prefix.

Parameters:prefix (str) – Prefix of the desired name.
Returns:Unique name in the current scope.
Return type:str
register(name, elem)[source]

Registers an addressable object with the desired name.

The name cannot exist in the scope, otherwise asserts False.

Parameters:
static reset_default_scope()[source]

Replaces the current default scope with a new empty scope.

deep_architect.core.determine_input_output_cleanup_seq(inputs)[source]

Determines the order in which the outputs can be cleaned.

This sequence is aligned with the module evaluation sequence. Positionally, after each module evaluation, the values stored in val for both inputs and outputs can be deleted. This is useful to remove intermediate results to save memory.

Note

This function should be used only for fully-specified search spaces.

Parameters:inputs (dict[str, deep_architect.core.Input]) – Dictionary of named inputs which by being traversed forward will reach all the modules in the search space.
Returns:List of lists with the inputs and outputs in the order they should be cleaned up after they are no longer needed.
Return type:(list[list[deep_architect.core.Input]], list[list[deep_architect.core.Output]])
deep_architect.core.determine_module_eval_seq(inputs)[source]

Computes the module forward evaluation sequence necessary to evaluate the computational graph starting from the provided inputs.

The computational graph is a directed acyclic graph. This function sorts the modules topologically based on their dependencies. It is assumed that the inputs in the dictionary provided are sufficient to compute forward for all modules in the graph. See also: forward().

Parameters:inputs (dict[str, deep_architect.core.Input]) – dictionary of inputs sufficient to compute the forward computation of the whole graph through propagation.
Returns:List of modules ordered in a way that allows to call forward on the modules in that order.
Return type:list[deep_architect.core.Module]
deep_architect.core.extract_unique_modules(input_or_output_lst)[source]

Get the modules associated to the inputs and outputs in the list.

Each module appears appear only once in the resulting list of modules.

Parameters:input_or_output_lst (list[deep_architect.core.Input or deep_architect.core.Output]) – List of inputs or outputs from which to extract the associated modules.
Returns:Unique modules to which the inputs and outputs in the list belong to.
Return type:list[deep_architect.core.Module]
deep_architect.core.forward(input_to_val, _module_seq=None)[source]

Forward pass through the graph starting with the provided inputs.

The starting inputs are given the values in the dictionary. The values for the other inputs are obtained through propagation, i.e., through successive calls to deep_architect.core.Module.forward() of the appropriate modules.

Note

For efficiency, in dynamic frameworks, the module evaluation sequence is best computed once and reused in each forward call. The module evaluation sequence is computed with determine_module_eval_seq().

Parameters:
deep_architect.core.get_all_hyperparameters(outputs)[source]

Going backward from the outputs provided, gets all hyperparameters.

Hyperparameters that can be reached by traversing dependency links between hyperparameters are also included. Setting an hyperparameter may lead to the creation of additional hyperparameters, which will be most likely not set. Such behavior happens when dealing with, for example, hyperparameters associated with substitutition modules such as deep_architect.modules.siso_optional(), deep_architect.modules.siso_or(), and deep_architect.modules.siso_repeat().

Parameters:outputs (dict[str, deep_architect.core.Output]) – Dictionary of named outputs to start the traversal at.
Returns:Ordered set of hyperparameters that are currently present in the graph.
Return type:OrderedSet[deep_architect.core.Hyperparameter]
deep_architect.core.get_modules_with_cond(outputs, cond_fn)[source]
deep_architect.core.get_unassigned_independent_hyperparameters(outputs)[source]

Going backward from the outputs provided, gets all the independent hyperparameters that are not set yet.

Setting an hyperparameter may lead to the creation of additional hyperparameters, which will be most likely not set. Such behavior happens when dealing with, for example, hyperparameters associated with substitutition modules such as deep_architect.modules.siso_optional(), deep_architect.modules.siso_or(), and deep_architect.modules.siso_repeat().

Parameters:outputs (dict[str, deep_architect.core.Output]) – Dictionary of named outputs to start the traversal at.
Returns:Ordered set of hyperparameters that are currently present in the graph and not have been assigned a value yet.
Return type:OrderedSet[deep_architect.core.Hyperparameter]
deep_architect.core.get_unconnected_inputs(outputs)[source]

Get the inputs that are reachable going backward from the provided outputs, but are not connected to any outputs.

Often, these inputs have to be provided with a value when calling forward().

Parameters:outputs (list[deep_architect.core.Output]) – Dictionary of named outputs to start the backward traversal at.
Returns:Unconnected inputs reachable by traversing the graph backward starting from the provided outputs.
Return type:list[deep_architect.core.Input]
deep_architect.core.get_unconnected_outputs(inputs)[source]

Get the outputs that are reachable going forward from the provided inputs, but are not connected to outputs.

Often, the final result of a forward pass through the network will be at these outputs.

Parameters:inputs (dict[str, deep_architect.core.Input]) – Dictionary of named inputs to start the forward traversal at.
Returns:Unconnected outputs reachable by traversing the graph forward starting from the provided inputs.
Return type:list[deep_architect.core.Output]
deep_architect.core.is_specified(outputs)[source]

Checks if all the hyperparameters reachable by traversing backward from the outputs have been set.

Parameters:outputs (dict[str, deep_architect.core.Output]) – Dictionary of named outputs to start the traversal at.
Returns:True if all the hyperparameters have been set. False otherwise.
Return type:bool
deep_architect.core.jsonify(inputs, outputs)[source]

Returns a JSON representation of the fully-specified search space.

This function is useful to create a representation of model that does not rely on the graph representation involving deep_architect.core.Module, deep_architect.core.Input, and deep_architect.core.Output.

Parameters:
Returns:

JSON representation of the fully specified model.
Return type:

(dict)
deep_architect.core.sorted_values_by_key(d)[source]
deep_architect.core.traverse_backward(outputs, fn)[source]

Backward traversal function through the graph.

Traverses the graph going from outputs to inputs. The provided function is applied once to each module reached this way. This function is used to implement other functionality that requires traversing the graph. fn typically has side effects, e.g., see is_specified() and get_unassigned_hyperparameters(). See also: traverse_forward().

Parameters:
deep_architect.core.traverse_forward(inputs, fn)[source]

Forward traversal function through the graph.

Traverses the graph going from inputs to outputs. The provided function is applied once to each module reached this way. This function is used to implement other functionality that requires traversing the graph. fn typically has side effects, e.g., see get_unconnected_outputs(). See also: traverse_backward().

Parameters:
deep_architect.core.unassigned_independent_hyperparameter_iterator(outputs)[source]

Returns an iterator over the hyperparameters that are not specified in the current search space.

This iterator is used by the searchers to go over the unspecified hyperparameters.

Note

It is assumed that all the hyperparameters that are touched by the iterator will be specified (most likely, right away). Otherwise, the iterator will never terminate.

Parameters:outputs (dict[str, deep_architect.core.Output]) – Dictionary of named outputs which by being traversed back will reach all the modules in the search space, and correspondingly all the current unspecified hyperparameters of the search space.
Yields:(deep_architect.core.Hyperparameter) – Next unspecified hyperparameter of the search space.

deep_architect.hyperparameters

deep_architect.modules

class deep_architect.modules.HyperparameterAggregator(name_to_hyperp, scope=None, name=None)[source]

Bases: deep_architect.core.Module

class deep_architect.modules.Identity(scope=None, name=None)[source]

Bases: deep_architect.core.Module

Module passes the input to the output without changes.

Parameters:
  • scope (deep_architect.core.Scope, optional) – Scope in which the module will be registered. If none is given, uses the default scope.
  • name (str, optional) – Name used to derive an unique name for the module. If none is given, uses the class name to derive the name.
class deep_architect.modules.SearchSpaceFactory(search_space_fn, reset_default_scope_upon_get=True)[source]

Bases: object

Helper used to provide a nicer interface to create search spaces.

The user should inherit from this class and implement _get_search_space(). The function get_search_space should be given to the searcher upon creation of the searcher.

Parameters:
get_search_space()[source]

Returns the buffered search space.

class deep_architect.modules.SubstitutionModule(name, substitution_fn, name_to_hyperp, input_names, output_names, scope=None, allow_input_subset=False, allow_output_subset=False)[source]

Bases: deep_architect.core.Module

Substitution modules are replaced by other modules when the all the hyperparameters that the module depends on are specified.

Substitution modules implement a form of delayed evaluation. The main component of a substitution module is the substitution function. When called, this function returns a dictionary of inputs and a dictionary of outputs. These outputs and inputs are used in the place the substitution module is in. The substitution module effectively disappears from the network after the substitution operation is done. Substitution modules are used to implement many other modules, e.g., mimo_or(), siso_optional(), and siso_repeat().

Parameters:
  • name (str) – Name used to derive an unique name for the module.
  • substitution_fn (dict[str, object] -> (dict[str, deep_architect.core.Input], dict[str, deep_architect.core.Output]) – Function that is called with the values of hyperparameters and returns the inputs and the outputs of the network fragment to put in the place the substitution module currently is.
  • name_to_hyperp (dict[str, deep_architect.core.Hyperparameter]) – Dictionary of name to hyperparameters that are needed for the substitution function. The names of the hyperparameters should be in correspondence to the name of the arguments of the substitution function.
  • input_names (list[str]) – List of the input names of the substitution module.
  • output_name (list[str]) – List of the output names of the substitution module.
  • scope ((deep_architect.core.Scope, optional)) – registered. If none is given, uses the default scope.
  • allow_input_subset (bool) – If true, allows the substitution function to return a strict subset of the names of the inputs existing before the substitution. Otherwise, the dictionary of inputs returned by the substitution function must contain exactly the same input names.
  • allow_output_subset (bool) – If true, allows the substitution function to return a strict subset of the names of the outputs existing before the substitution. Otherwise, the dictionary of outputs returned by the substitution function must contain exactly the same output names.
_update()[source]

Implements the substitution operation.

When all the hyperparameters that the module depends on are specified, the substitution operation is triggered, and the substitution operation is done.

deep_architect.modules.buffer_io(inputs, outputs)[source]
deep_architect.modules.dense_block(h_num_applies, h_end_in_combine, apply_fn, combine_fn, scope=None, name=None)[source]
deep_architect.modules.get_hyperparameter_aggregators(outputs)[source]
deep_architect.modules.hyperparameter_aggregator(name_to_hyperp, scope=None, name=None)[source]
deep_architect.modules.identity(scope=None, name=None)[source]

Same as the Identity module, but directly works with dictionaries of inputs and outputs of the module.

See Identity.

Returns:Tuple with dictionaries with the inputs and outputs of the module.
Return type:(dict[str,deep_architect.core.Input], dict[str,deep_architect.core.Output])
deep_architect.modules.mimo_nested_repeat(fn_first, fn_iter, h_num_repeats, input_names, output_names, scope=None, name=None)[source]

Nested repetition substitution module.

The first function function returns a dictionary of inputs and a dictionary of outputs, and it is always called once. The second function takes the previous dictionaries of inputs and outputs and returns new dictionaries of inputs and outputs. The names of the inputs and outputs returned by the functions have to match the names of the inputs and outputs of the substitution module. The resulting network fragment is used in the place of the substitution module.

Parameters:
Returns:

Tuple with dictionaries with the inputs and outputs of the substitution module.
Return type:

(dict[str,deep_architect.core.Input], dict[str,deep_architect.core.Output])
deep_architect.modules.mimo_or(fn_lst, h_or, input_names, output_names, scope=None, name=None)[source]

Implements an or substitution operation.

The hyperparameter takes values that are valid indices for the list of possible substitution functions. The set of keys of the dictionaries of inputs and outputs returned by the substitution functions have to be the same as the set of input names and output names, respectively. The substitution function chosen is used to replace the current substitution module, with connections changed appropriately.

Note

The current implementation also works if fn_lst is an indexable object (e.g., a dictionary), and the h_or takes values that are valid indices for the indexable (e.g., valid keys for the dictionary).

Parameters:
Returns:

Tuple with dictionaries with the inputs and outputs of the substitution module.
Return type:

(dict[str,deep_architect.core.Input], dict[str,deep_architect.core.Output])
deep_architect.modules.preproc_apply_postproc(preproc_fn, apply_fn, postproc_fn)[source]
deep_architect.modules.siso_nested_repeat(fn_first, fn_iter, h_num_repeats, scope=None, name=None)[source]

Nested repetition substitution module.

Similar to mimo_nested_repeat(), the only difference being that in this case the function returns an or substitution module that has a single input and a single output.

The first function function returns a dictionary of inputs and a dictionary of outputs, and it is always called. The second function takes the previous dictionaries of inputs and outputs and returns new dictionaries of inputs and outputs. The resulting network fragment is used in the place of the current substitution module.

Parameters:
Returns:

Tuple with dictionaries with the inputs and outputs of the substitution module.
Return type:

(dict[str,deep_architect.core.Input], dict[str,deep_architect.core.Output])
deep_architect.modules.siso_optional(fn, h_opt, scope=None, name=None)[source]

Substitution module that determines to include or not the search space returned by fn.

The hyperparameter takes boolean values (or equivalent integer zero and one values). If the hyperparameter takes the value False, the input is simply put in the output. If the hyperparameter takes the value True, the search space is instantiated by calling fn, and the substitution module is replaced by it.

Parameters:
Returns:

Tuple with dictionaries with the inputs and outputs of the substitution module.
Return type:

(dict[str,deep_architect.core.Input], dict[str,deep_architect.core.Output])
deep_architect.modules.siso_or(fn_lst, h_or, scope=None, name=None)[source]

Implements an or substitution operation.

The hyperparameter takes values that are valid indices for the list of possible substitution functions. The substitution function chosen is used to replace the current substitution module, with connections changed appropriately.

See also mimo_or().

Note

The current implementation also works if fn_lst is an indexable object (e.g., a dictionary), and the h_or takes values that are valid indices for the dictionary.

Parameters:
Returns:

Tuple with dictionaries with the inputs and outputs of the substitution module.
Return type:

(dict[str,deep_architect.core.Input], dict[str,deep_architect.core.Output])
deep_architect.modules.siso_permutation(fn_lst, h_perm, scope=None, name=None)[source]

Substitution module that permutes the sub-search spaces returned by the functions in the list and connects them sequentially.

The hyperparameter takes positive integer values that index the possible permutations of the number of elements of the list provided, i.e., factorial in the length of the list possible values (zero indexed). The list is permuted according to the permutation chosen. The search spaces resulting from calling the functions in the list are connected sequentially.

Parameters:
Returns:

Tuple with dictionaries with the inputs and outputs of the substitution module.
Return type:

(dict[str,deep_architect.core.Input], dict[str,deep_architect.core.Output])
deep_architect.modules.siso_repeat(fn, h_num_repeats, scope=None, name=None)[source]

Calls the function multiple times and connects the resulting graph fragments sequentially.

Parameters:
Returns:

Tuple with dictionaries with the inputs and outputs of the substitution module.
Return type:

(dict[str,deep_architect.core.Input], dict[str,deep_architect.core.Output])
deep_architect.modules.siso_residual(main_fn, residual_fn, combine_fn)[source]

Residual connection of two functions returning search spaces encoded as pairs of dictionaries of inputs and outputs.

The third function returns a search space to continue the main and residual path search spaces. See also: siso_split_combine(). The main and residual functions return search space graphs with a single input and a single output . The combine function returns a search space with two inputs and a single output.

Note

Specific names are assumed for the inputs and outputs of the different search spaces.

Parameters:
Returns:

Tuple with dictionaries with the inputs and outputs of the resulting search space graph.
Return type:

(dict[str,deep_architect.core.Input], dict[str,deep_architect.core.Output])
deep_architect.modules.siso_sequential(io_lst)[source]

Connects in a serial connection a list of dictionaries of the inputs and outputs encoding single-input single-output search spaces.

Parameters:io_lst (list[(dict[str,deep_architect.core.Input], dict[str,deep_architect.core.Output])]) – List of single-input single-output dictionaries encoding
Returns:Tuple with dictionaries with the inputs and outputs of the resulting graph resulting from the sequential connection.
Return type:(dict[str,deep_architect.core.Input], dict[str,deep_architect.core.Output])
deep_architect.modules.siso_split_combine(fn, combine_fn, h_num_splits, scope=None, name=None)[source]

Substitution module that create a number of parallel single-input single-output search spaces by calling the first function, and then combines all outputs with a multiple-input single-output search space returned by the second function.

The second function returns a search space to combine the outputs of the branch search spaces. The hyperparameter captures how many branches to create. The resulting search space has a single input and a single output.

Note

It is assumed that the inputs and outputs of both the branch search spaces and the reduce search spaces are named in a specific way.

Parameters:
Returns:

Tuple with dictionaries with the inputs and outputs of the resulting search space graph.
Return type:

(dict[str,deep_architect.core.Input], dict[str,deep_architect.core.Output])
deep_architect.modules.substitution_module(name, substitution_fn, name_to_hyperp, input_names, output_names, scope=None, allow_input_subset=False, allow_output_subset=False)[source]

Same as the substitution module, but directly works with the dictionaries of inputs and outputs.

A dictionary with inputs and a dictionary with outputs is the preferred way of dealing with modules when creating search spaces. Using inputs and outputs directly instead of modules allows us to return graphs in the substitution function. In this case, returning a graph resulting of the connection of multiple modules is entirely transparent to the substitution function.

See also: deep_architect.modules.SubstitutionModule.

Parameters:
  • name (str) – Name used to derive an unique name for the module.
  • substitution_fn (dict[str, object] -> (dict[str, deep_architect.core.Input], dict[str, deep_architect.core.Output]) – Function that is called with the values of hyperparameters and values of inputs and returns the inputs and the outputs of the network fragment to put in the place the substitution module currently is.
  • name_to_hyperp (dict[str, deep_architect.core.Hyperparameter]) – Dictionary of name to hyperparameters that are needed for the substitution function. The names of the hyperparameters should be in correspondence to the name of the arguments of the substitution function.
  • input_names (list[str]) – List of the input names of the substitution module.
  • output_name (list[str]) – List of the output names of the substitution module.
  • scope (deep_architect.core.Scope) – Scope in which the module will be registered.
  • allow_input_subset (bool) – If true, allows the substitution function to return a strict subset of the names of the inputs existing before the substitution. Otherwise, the dictionary of inputs returned by the substitution function must contain exactly the same input names.
  • allow_output_subset (bool) – If true, allows the substitution function to return a strict subset of the names of the outputs existing before the substitution. Otherwise, the dictionary of outputs returned by the substitution function must contain exactly the same output names.
Returns:

Tuple with dictionaries with the inputs and outputs of the module.
Return type:

(dict[str,deep_architect.core.Input], dict[str,deep_architect.core.Output])

deep_architect.search_logging

class deep_architect.search_logging.EvaluationLogger(folderpath, search_name, evaluation_id, abort_if_exists=False, abort_if_notexists=False)[source]

Bases: object

Evaluation logger for a simple evaluation.

The logging is divided into config and results. Both are represented as JSON files in disk, i.e., dictionaries. The config JSON encodes the architecture to be evaluated. This encoding is tied to the search space the evaluation was drawn from, and it can be used to reproduce the architecture to be evaluated given the search space.

The results JSON contains the results of the evaluating the particular architecture. In the case of deep learning, this often involves training the architecture for a given task on a training set and evaluating it on a validation set.

Parameters:
  • all_evaluations_folderpath (str) – Path to the folder where all the evaluation log folders lie. This folder is managed by the search logger.
  • evaluation_id (int) – Number of the evaluation with which the logger is associated with. The numbering starts at zero.
config_exists()[source]
get_evaluation_data_folderpath()[source]

Path to the user data folder where non-standard logging data can be stored.

This is useful to store additional information about the evaluated model, e.g., example predictions of the model, model weights, or model predictions on the validation set.

See deep_architect.search_logging.EvaluationLogger.get_evaluation_folderpath() for the path for the standard JSON logs for an evaluation.

Returns:Path to the folder where the evaluations logs are written to.
Return type:str
get_evaluation_folderpath()[source]

Path to the evaluation folder where all the standard evaluation logs (e.g., config.json and results.json) are written to.

Only standard logging information about the evaluation should be written here. See deep_architect.search_logging.EvaluationLogger.get_evaluation_data_folderpath() for a path to a folder that can be used to store non-standard user logging information.

Returns:Path to the folder where the standard logs about the evaluation are written to.
Return type:str
log_config(hyperp_value_lst, searcher_evaluation_token)[source]

Logs a config JSON that describing the evaluation to be done.

The config JSON has the list with the ordered sequence of hyperparameter values that allow to replicate the same evaluation given the same search space; the searcher evaluation token, that can be given back to the same searcher allowing it to update back its state. The searcher evaluation token is returned by the searcher when a new architecture to evaluate is sampled. See, for example, deep_architect.searchers.MCTSSearcher.sample(). The format of the searcher evaluation token is searcher dependent, but it should be JSON serializable in all cases.

Creates config.json in the evaluation log folder.

Parameters:
  • hyperp_value_lst (list[object]) – List with the sequence of JSON serializable hyperparameter values that define the architecture to evaluate.
  • searcher_evaluation_token (dict[str, object]) – Dictionary that is JSON serializable and it is enough, when given back to the searcher along with the results, for the searcher to update its state appropriately.
log_results(results)[source]

Logs the results of evaluating an architecture.

The dictionary contains many metrics about the architecture.. In machine learning, this often involves training the model on a training set and evaluating the model on a validation set. In domains different than machine learning, other forms of evaluation may make sense.

Creates results.json in the evaluation log folder.

Parameters:dict[object] – Dictionary of JSON serializable metrics and information about the evaluated architecture.
read_config()[source]
read_results()[source]
results_exist()[source]
class deep_architect.search_logging.SearchLogger(folderpath, search_name, abort_if_exists=True, delete_if_exists=False)[source]

Bases: object

get_evaluation_logger(evaluation_id, abort_if_exists=False, abort_if_notexists=False)[source]
deep_architect.search_logging.create_search_folderpath(folderpath, search_name, abort_if_exists=False, delete_if_exists=False, create_parent_folders=False)[source]
deep_architect.search_logging.get_all_evaluations_folderpath(folderpath, search_name)[source]
deep_architect.search_logging.get_evaluation_data_folderpath(folderpath, search_name, evaluation_id)[source]
deep_architect.search_logging.get_evaluation_folderpath(folderpath, search_name, evaluation_id)[source]
deep_architect.search_logging.get_search_data_folderpath(folderpath, search_name)[source]
deep_architect.search_logging.get_search_folderpath(folderpath, search_name)[source]
deep_architect.search_logging.is_search_log_folder(folderpath)[source]
deep_architect.search_logging.read_evaluation_folder(evaluation_folderpath)[source]

Reads all the standard JSON log files associated to a single evaluation.

See also deep_architect.search_logging.read_search_folder() for the function that reads all the evaluations in a search folder.

Parameters:evaluation_folderpath (str) – Path to the folder containing the standard JSON logs.
Returns:Nested dictionaries with the logged information. The first dictionary has keys corresponding to the names of the standard log files.
Return type:dict[str,dict[str,object]]
deep_architect.search_logging.read_search_folder(search_folderpath)[source]

Reads all the standard JSON log files associated to a search experiment.

See also deep_architect.search_logging.read_evaluation_folder() for the function that reads a single evaluation folder. The list of dictionaries is ordered in increasing order of evaluation id.

Parameters:search_folderpath (str) – Path to the search folder used for logging.
Returns:List of nested dictionaries with the logged information. Each dictionary in the list corresponds to an evaluation.
Return type:list[dict[str,dict[str,object]]]
deep_architect.search_logging.recursive_list_log_folders(folderpath)[source]
deep_architect.search_logging.recursive_read_search_folders(folderpath)[source]

deep_architect.searchers

deep_architect.helpers

deep_architect.surrogates

class deep_architect.surrogates.common.SurrogateModel[source]

Bases: object

Abstract class for a surrogate model.

eval(feats)[source]

Returns a prediction of performance (or other relevant metrics), given a feature representation of the architecture.

update(val, feats)[source]

Updates the state of the surrogate function given the feature representation for the architecture and the corresponding ground truth performance metric.

Note

The data for the surrogate model may be kept internally. The update of the state of the surrogate function can be done periodically, rather than with each call to update. This can be done based on values for the configuration of the surrogate model instance.

deep_architect.surrogates.common.extract_features(inputs, outputs)[source]

Extract a feature representation of a model represented through inputs and outputs.

This function has been mostly used for performance prediction on fully specified models, i.e., after all the hyperparameters in the search space have specified. After this, there is a single model for which we can compute an appropriate feature representation containing information about the connections that the model makes and the values of the hyperparameters.

Parameters:
Returns:

Representation of the architecture as a dictionary where each key is associated to a list with different types of features.
Return type:

dict[str, list[str]]

deep_architect.visualization