DeeplayModule#

class deeplay.module.DeeplayModule(*args, **kwargs)#

Bases: Module

A base class for creating configurable, extensible modules with dynamic initialization and argument management. This class is designed to be subclassed for specific functional implementations. It extends nn.Module and utilizes a custom meta-class, ExtendedConstructorMeta, for enhanced construction logic.

Attributes#

__extra_configurables__list[str]

List of additional configurable attributes.

configurablesset[str]

A property that returns a set of configurable attributes for the module.

kwargsdict

A property to get or set keyword arguments.

Methods#

configure(*args: Any, **kwargs: Any)

Configures the module with given arguments and keyword arguments.

create()

This method creates and returns a new instance of the module. Unlike build, which modifies the module in place, create initializes a fresh instance with the current configuration and state, ensuring that the original module remains unchanged

build()

build: “This method modifies the current instance of the module in place. It finalizes the setup of the module, applying any necessary configurations or adjustments directly to the existing instance.”

new()

Creates a new instance of the module with collected user configuration.

get_user_configuration()

Retrieves the current user configuration of the module.

get_argspec()

Class method to get the argument specification of the module’s initializer.

get_signature()

Class method to get the signature of the module’s initializer.

Example Usage#

To subclass DeeplayModule, define an __init__ method and other necessary methods:

``` class MyModule(DeeplayModule):

def __init__(self, param1, param2):

super().__init__() # Initialize your module here

```

To use the module:

` module = MyModule(param1=value1, param2=value2) module.configure(param1=some_value, param2=some_other_value) built_module = module.build() `

Attributes Summary

configurables

device

dtype

is_constructing

kwargs

logs

root_module

tags

Methods Summary

__call__(*args, **kwargs)

Call self as a function.

available_styles()

build(*args, **kwargs)

Modifies the current instance of the module in place, finalizing its setup.

calling_stateful()

computed(_x[, _f])

Register a computed value.

configure(*args, **kwargs)

Configures the module with specified arguments.

create()

Creates and returns a new instance of the module, fully initialized with the current configuration.

forward(*args, **kwargs)

Define the computation performed at every call.

get_argspec()

get_from_user_config(key)

get_init_args()

get_signature()

get_subconfig()

get_user_configuration()

Retrieves the current user configuration of the module.

getitem_with_selections(selector[, selections])

initialize(initializer[, tensors])

log_input(name)

log_output(name)

log_tensor(name, tensor)

Stores a tensor in the root log.

new([detach, memo])

predict(x, *args[, batch_size, device, ...])

Predicts the output of the module for the given input.

register_after_build_hook(func)

Registers a function to be called after the module is built.

register_after_init_hook(func)

Registers a function to be called after the module is initialized.

register_before_build_hook(func)

Registers a function to be called before the module is built.

register_style(func)

replace(target, replacement)

Replaces a child module with another module.

set(name, value)

Sets an attribute for the module, allowing for persistent configuration across checkpoints.

set_input_map(*args, **kwargs)

set_output_map(*args, **kwargs)

set_root_module(value)

style(style, *args, **kwargs)

styled(style, *args, **kwargs)

Attributes Documentation

configurables#
device#
dtype#
is_constructing#
kwargs#
logs: Dict[str, Any]#
root_module#
tags#

Methods Documentation

__call__(*args, **kwargs)#

Call self as a function.

classmethod available_styles()#
build(*args, **kwargs) → DeeplayModule#

Modifies the current instance of the module in place, finalizing its setup.

The build method is essential for completing the initialization of the module. It applies the necessary configurations and adjustments directly to the existing instance. Unlike create, which generates a new module instance, build works on the current module instance. This method is particularly crucial for subclasses of dl.External, as it triggers the instantiation of actual torch layers (like Linear, Sigmoid, ReLU, etc.) within the module. For most other objects, build primarily serves to finalize their configuration.

Note that build is automatically called within the create method, ensuring that newly created instances are fully initialized and ready for use.

Parameters#

*args, **kwargsAny

Example input to the forward method used to

Returns#

DeeplayModule

The current instance of the module after applying all configurations and adjustments.

Example Usage#

Finalizing the setup of a module instance with build: ` module = ExampleModule(a=0) module.configure(a=1) built_module = module.build() # `built_module` is the same instance as `module`, now fully configured and initialized `

calling_stateful()#
computed(_x: Callable | str, _f: Callable | None = None)#

Register a computed value.

Can be used as a decorator or as a function. If the first argument is a string, it is assumed to be the name of the computed value. If the second argument is not set, the function is used as a decorator. If the first argument is a function, it is assumed to be the function to be computed, and the name of the function is used as the name of the computed value.

Parameters#

_xUnion[Callable, str]

The function to be computed or the name of the computed value.

_fOptional[Callable], optional

The function to be computed, by default None.

Examples#

As a decorator: >>> @module.computed(“in_features”) >>> def f(x): >>> return x.shape[1]

As a function: >>> module.computed(“in_features”, lambda x: x.shape[1])

As with a function >>> def in_features(x): >>> return x.shape[1] >>> module.computed(in_features)

configure(*args: Any, **kwargs: Any)#

Configures the module with specified arguments.

This method allows dynamic configuration of the module’s properties and behaviors. It can be used to set or modify the attributes and parameters of the module and, if applicable, its child modules. The method intelligently handles both direct attribute configuration and delegation to child modules’ configure methods.

Parameters#

*argsAny

Positional arguments specifying the configuration settings. When the first argument is a string matching a configurable attribute, the method expects either one or two arguments: the attribute name and, optionally, its value. If the attribute is itself a DeeplayModule, subsequent arguments are passed to its configure method.

**kwargsAny

Keyword arguments for configuration settings. If provided, these are used to update the module’s configuration directly.

Raises#

ValueError

Raised if a configuration key is not recognized as a valid configurable for the module or if the provided arguments do not match the expected pattern for configuration.

Example Usage#

To configure a single attribute: ` module.configure('attribute_name', attribute_value) # or module.configure(attribute_name=attribute_value) `

To configure multiple attributes using keyword arguments: ` module.configure(attribute1=value1, attribute2=value2) `

To configure a child module’s attribute: ` module.configure('child_module_attribute', child_attribute=child_attribute_value) # or module.child_module.configure(child_attribute=child_attribute_value) `

create() → Self#

Creates and returns a new instance of the module, fully initialized with the current configuration.

This method differs from build in that it generates a new, independent instance of the module, rather than modifying the existing one. It’s particularly relevant for subclasses of dl.External, where actual torch layers (like Linear, Sigmoid, ReLU, etc.) are instantiated during the build process. For these subclasses, create not only configures but also instantiates the specified torch layers. For most other objects, the .build() step, which is internally called in create, has no additional effect beyond configuration.

Returns#

DeeplayModule

A new instance of the DeeplayModule (or its subclass), initialized with the current module’s configuration and, for dl.External subclasses, with instantiated torch layers.

Example Usage#

Creating a dl.Layer instance and then fully initializing it with create: ` layer = dl.Layer(nn.Linear, in_features=20, out_features=40) # At this point, `layer` has not instantiated nn.Linear built_layer = layer.create() # Now, `built_layer` is an instance of nn.Linear(in_features=20, out_features=40) `

forward(*args, **kwargs)#

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

classmethod get_argspec()#
get_from_user_config(key)#
get_init_args()#
classmethod get_signature()#
get_subconfig()#
get_user_configuration()#

Retrieves the current user configuration of the module.

This method returns a dictionary containing the configuration settings provided by the user for this module. It is useful for inspecting the current state of module configuration, especially after multiple configurations have been applied or when the module’s configuration needs to be examined or debugged.

Returns#

dict

A dictionary containing the current user configuration settings. The keys are tuples representing the configuration attributes, and the values are the corresponding settings.

Example Usage#

To retrieve the current configuration of a module: ` module = ExampleModule(a=0) module.configure(a=1) current_config = module.get_user_configuration() # current_config == {('a',): 1} `

getitem_with_selections(selector, selections=None)#
initialize(initializer, tensors: str | Tuple[str, ...] = ('weight', 'bias'))#
log_input(name: str)#
log_output(name: str)#
log_tensor(name: str, tensor: Tensor)#

Stores a tensor in the root log.

Allows for storing tensors in the root module’s logs. Can be used in inference to make tensors globally available outside the direct forward pass.

Parameters#

namestr

The name of the tensor to store.

tensortorch.Tensor

The tensor to store in the logs.

new(detach: bool = True, memo=None) → Self#
predict(x, *args, batch_size=32, device=None, output_device=None) → Tensor#

Predicts the output of the module for the given input.

This method is a wrapper around the forward method, which is used to predict the output of the module for the given input. It is particularly useful for making predictions on large datasets, as it allows for the specification of a batch size for processing the input data.

Parameters#

xarray-like

The input data for which to predict the output. Should be an array-like object with the same length as the input data.

*argsAny

Positional arguments for the input data. Should have the same length as the input data.

batch_sizeint, optional

The batch size for processing the input data. Defaults to 32.

devicestr, Device, optional

The device on which to perform the prediction. If None, the model’s device is used. Defaults to None.

output_devicestr, Device, optional

The device on which to store the output. If None, the model’s device is used. Defaults to None.

Returns#

Any

The output of the module for the given input data.

Example Usage#

To predict the output of a module for the given input data: ` module = ExampleModule() output = module.predict(input_data, batch_size=64) `

register_after_build_hook(func)#

Registers a function to be called after the module is built.

Parameters#

funcCallable

The function to be called after the module is built. The function should take a single argument, which is the module instance.

register_after_init_hook(func)#

Registers a function to be called after the module is initialized.

Parameters#

funcCallable

The function to be called after the module is initialized. The function should take a single argument, which is the module instance.

register_before_build_hook(func)#

Registers a function to be called before the module is built.

Parameters#

funcCallable

The function to be called before the module is built. The function should take a single argument, which is the module instance.

classmethod register_style(func)#
replace(target: str, replacement: Module)#

Replaces a child module with another module.

This method replaces the child module with the given name with the specified replacement module. It is useful for dynamically swapping out modules within a larger module or for replacing modules within a module that has already been built.

Parameters#

targetstr

The name of the child module to be replaced.

replacementDeeplayModule

The replacement module.

Raises#

ValueError

Raised if the target module is not found among the module’s children.

Example Usage#

To replace a child module with another module: ` module = ExampleModule() module.replace('child_module', ReplacementModule()) `

set(name, value)#

Sets an attribute for the module, allowing for persistent configuration across checkpoints.

This method is intended for setting module parameters or configurations that should be restored when loading a module from a saved checkpoint.

Parameters#

name: str

The name of the attribute to set.

value: any

The value to assign to the attribute.

Example#

>>> module.set("attribute", 42)
>>> module.attribute
42
set_input_map(*args: str, **kwargs: str)#
set_output_map(*args: str, **kwargs: int)#
set_root_module(value)#
style(style: str, *args, **kwargs) → Self#
styled(style: str, *args, **kwargs) → Self#