Adapter Subsystem
- class golem.core.adapter.adapt_registry.AdaptRegistry(*args, **kwargs)[source]
Bases:
object
Registry of callables that require adaptation of argument/return values. AdaptRegistry together with
golem.core.adapter.adapter.BaseOptimizationAdapter
enables automatic transformation between internal and domain graph representations.Short description of the use-case
Operators & verification rules that operate on internal representation of graphs must be marked as native with decorator
golem.core.adapter.adapt_registry.register_native()
.Usually this is the case when users of the framework provide custom operators for internal optimization graphs. When custom operators operate on domain graphs, nothing is required.
Extended description
Optimiser operates with generic graph representation. Because of this any domain function requires adaptation of its graph arguments. Adapter can automatically adapt arguments to generic form in such cases.
Important notions:
‘Domain’ functions operate with domain-specific graphs.
‘Native’ functions operate with generic graphs used by optimiser.
‘External’ functions are functions defined by users of optimiser.
Most notably, custom mutations and custom verifier rules.
‘Internal’ functions are those defined by graph optimiser.
Most notably, the default set of mutations and verifier rules. All internal functions are native.
Adaptation registry usage and behavior:
Domain functions are adapted by default.
Native functions don’t require adaptation of their arguments.
External functions are considered ‘domain’ functions by default.
Hence, their arguments are adapted, unless users of optimiser exclude them from the process of automatic adaptation. It can be done by registering them as ‘native’.
AdaptRegistry can be safely used with multiprocessing insofar as all relevant functions are registered as native in the main process before child processes are started.
- register_native(fun: Callable) Callable [source]
Registers callable object as an internal function that can work with internal graph representation. Hence, it doesn’t require adaptation when called by the optimiser.
Implementation details. Works by setting a special attribute on the object. This attribute then is checked by
is_native
used by adapters.- Parameters
fun – function or callable to be registered as native
- Returns
same function with special private attribute set
- Return type
Callable
- unregister_native(fun: Callable) Callable [source]
Unregisters callable object. See
register_native
.- Parameters
fun – function or callable to be unregistered as native
- Returns
same function with special private attribute unset
- Return type
Callable
- static is_native(fun: Callable) bool [source]
Tests callable object for a presence of specific attribute that tells that this function must not be restored with Adapter.
- Parameters
fun – tested Callable (function, method, functools.partial, or any callable object)
- Returns
True if the callable was registered as native, False otherwise.
- Return type
bool
- golem.core.adapter.adapt_registry.register_native(fun: Callable) Callable [source]
Out-of-class version of the
register_native
function that’s intended to be used as a decorator.- Parameters
fun – function or callable to be registered as native
- Returns
same function with special private attribute set
- Return type
Callable
- class golem.core.adapter.adapter.BaseOptimizationAdapter(base_graph_class: Type[golem.core.adapter.adapter.DomainStructureType] = <class 'golem.core.dag.graph.Graph'>)[source]
Bases:
Generic
[golem.core.adapter.adapter.DomainStructureType
]- restore_func(fun: Callable) Callable [source]
Wraps native function so that it could accept domain graphs as arguments.
Behavior:
restore( f(Graph)->Graph ) => f'(DomainGraph)->DomainGraph
Implementation details. The method wraps callable into a function that transforms its args & return value. Arguments are transformed by
adapt
(that maps domain graphs to internal graphs). Return value is transformed byrestore
(that maps internal graphs to domain graphs).- Parameters
fun – native function that accepts native args (i.e. optimization graph)
- Returns
domain function that can accept domain graphs
- Return type
Callable
- adapt_func(fun: Callable) Callable [source]
Wraps domain function so that it could accept native optimization graphs as arguments. If the function was registered as native, it is returned as-is.
AdaptRegistry
is responsible for function registration.Behavior:
adapt( f(DomainGraph)->DomainGraph ) => f'(Graph)->Graph
Implementation details. The method wraps callable into a function that transforms its args & return value. Arguments are transformed by
restore
(that maps internal graphs to domain graphs). Return value is transformed byadapt
(that maps domain graphs to internal graphs).- Parameters
fun – domain function that accepts domain graphs
- Returns
native function that can accept opt graphs and be used inside Optimizer
- Return type
Callable
- adapt(item: Union[golem.core.adapter.adapter.DomainStructureType, Sequence[golem.core.adapter.adapter.DomainStructureType]]) Union[golem.core.dag.graph.Graph, Sequence[golem.core.dag.graph.Graph]] [source]
Maps domain graphs to internal graph representation used by optimizer. Performs mapping only if argument has a type of domain graph.
- Parameters
item – a domain graph or sequence of them
- Returns
mapped internal graph or sequence of them
- Return type
Graph | Sequence
- restore(item: Union[Graph, Individual, PopulationT, Sequence[Graph]]) Union[DomainStructureType, Sequence[DomainStructureType]] [source]
Maps graphs from internal representation to domain graphs. Performs mapping only if argument has a type of internal representation.
- Parameters
item – an internal graph representation or sequence of them
- Returns
mapped domain graph or sequence of them
- Return type
Graph | Sequence
- abstract _adapt(adaptee: golem.core.adapter.adapter.DomainStructureType) golem.core.dag.graph.Graph [source]
Implementation of
adapt
for single graph.
- abstract _restore(opt_graph: golem.core.dag.graph.Graph, metadata: Optional[Dict[str, Any]] = None) golem.core.adapter.adapter.DomainStructureType [source]
Implementation of
restore
for single graph.
- class golem.core.adapter.adapter.IdentityAdapter(base_graph_class: Type[golem.core.adapter.adapter.DomainStructureType] = <class 'golem.core.dag.graph.Graph'>)[source]
Bases:
golem.core.adapter.adapter.BaseOptimizationAdapter
[golem.core.adapter.adapter.DomainStructureType
]Identity adapter that performs no transformation, returning same graphs.
- class golem.core.adapter.adapter.DirectAdapter(base_graph_class: Type[golem.core.adapter.adapter.DomainStructureType] = <class 'golem.core.dag.graph_delegate.GraphDelegate'>, base_node_class: Type = <class 'golem.core.dag.linked_graph_node.LinkedGraphNode'>)[source]
Bases:
golem.core.adapter.adapter.BaseOptimizationAdapter
[golem.core.adapter.adapter.DomainStructureType
]Naive optimization adapter for arbitrary class that just overwrites __class__.
- golem.core.adapter.adapter._transform(fun: Callable, f_args: Callable, f_ret: Callable) Callable [source]
- Wraps function by transforming its arguments and return value:
f_args
is called on each of the function arguments,f_ret
is called on the return value of original function.This is a helper function used for adaption of callables by
golem.core.adapter.adapter.BaseOptimizationAdapter
.
- Parameters
fun – function to be transformed
f_args – argument transformation function
f_ret – return value transformation function
- Returns
wrapped transformed function
- Return type
Callable