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

static _get_underlying_func(obj: Callable) → Callable[source]

Recursively unpacks ‘partial’ and ‘method’ objects to get underlying function.

Parameters: obj – callable to try unpacking
Returns: unpacked function that underlies the callable, or the unchanged object itself
Return type: Callable

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 by restore (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 by adapt (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