Plugin Manager

ropt.plugins.Plugin

Bases: ABC

Abstract base class for all ropt plugins.

This class serves as the fundamental building block for all plugins within the ropt framework. Any class intended to function as a plugin (e.g., an optimizer, sampler, or event handler) must inherit from this base class.

It defines the core interface that all plugins must adhere to, ensuring consistency and enabling the PluginManager to discover and manage them effectively.

Subclasses must implement the is_supported class method to indicate which named methods (functionalities) they provide. They can optionally override the allows_discovery class method if they should not be automatically selected by the plugin manager when a method name is provided without an explicit plugin name.

is_supported abstractmethod classmethod

is_supported(method: str) -> bool

Verify if this plugin supports a specific named method.

This class method is used by the PluginManager (specifically its get_plugin_name method) to determine if this plugin class provides the functionality associated with the given method name.

Parameters:

Name	Type	Description	Default
method	str	The string identifier of the method to check for support.	required

Returns:

Type	Description
bool	True if the plugin supports the specified method, False otherwise.

allows_discovery classmethod

allows_discovery() -> bool

Determine if the plugin allows implicit discovery by method name.

By default (True), plugins can be found by the PluginManager when a user provides only a method name (without specifying the plugin, e.g., "method-name").

If a plugin should only be used when explicitly named (e.g., "plugin-name/method-name"), it must override this class method to return False.

For instance, the external optimizer plugin acts as a wrapper for other optimizers run in separate processes. It doesn't provide methods directly and must always be explicitly requested, so it overrides this method to return False.

Returns:

Type	Description
bool	True if the plugin can be discovered implicitly by method name.

ropt.plugins.manager.PluginManager

Manages the discovery and retrieval of ropt plugins.

The PluginManager is responsible for finding available plugins based on Python's entry points mechanism and providing access to them. It serves as a central registry for different types of plugins used within ropt, such as optimizers, samplers, and workflow components.

Upon initialization, the manager scans for entry points defined under the ropt.plugins.* groups (e.g., ropt.plugins.backend). Plugins found this way are loaded and stored internally, categorized by their type.

The primary way to interact with the manager is through the get_plugin method, which retrieves a specific plugin class based on its type and a method name it supports. The get_plugin_name method can be used to find the name of a plugin that supports a given method.

Example: Registering a Custom Backend Plugin

To make a custom optimization backend plugin available to ropt, you would typically define an entry point in your package's pyproject.toml:

[project.entry-points."ropt.plugins.backend"]
my_backend = "my_package.my_module:MyBackend"

When ropt initializes the PluginManager, it will discover and load MyBackend from my_package.my_module, making it accessible via plugin_manager.get_plugin("backend", "my_backend/some_method") or potentially plugin_manager.get_plugin("backend", "some_method") if discovery is allowed and the method is unique.

__init__

__init__() -> None

Initialize the plugin manager.

get_plugin

get_plugin(plugin_type: PluginType, method: str) -> Any

Retrieve a plugin class by its type and a supported method name.

This method finds and returns the class of a plugin that matches the specified plugin_type and supports the given method.

The method argument can be specified in two ways:

1. Explicit Plugin: Use the format "plugin-name/method-name". This directly requests the method-name from the plugin named plugin-name.
2. Implicit Plugin: Provide only the method-name. The manager will search through all registered plugins of the specified plugin_type that allow discovery (see Plugin.allows_discovery). If the method is found in the default plugin of ropt, that plugin is used. Otherwise it returns the first plugin found that supports the method-name.

Parameters:

Name	Type	Description	Default
plugin_type	PluginType	The category of the plugin (e.g., "backend", "sampler").	required
method	str	The name of the method the plugin must support, potentially prefixed with the plugin name and a slash (/).	required

Returns:

Type	Description
Any	The plugin class that matches the criteria.

Raises:

Type	Description
ValueError	If no matching plugin is found for the given type and method, or if "default" is used as a method name without specifying a plugin name.

get_plugin_name

get_plugin_name(
    plugin_type: PluginType, method: str
) -> str | None

Return the name of the plugin that supports a given method.

Verifies whether a plugin of the specified plugin_type supports the given method. This is useful for checking availability before attempting to retrieve a plugin with get_plugin.

The method argument can be specified in two ways:

1. Explicit Plugin: "plugin-name/method-name" checks if the specific plugin named plugin-name supports method-name.
2. Implicit Plugin: "method-name" searches through all discoverable plugins of the given plugin_type to see if any support method-name. If the method is found in the default plugin of ropt, that plugin is used. Otherwise it returns the first plugin found that supports the method-name.

Parameters:

Name	Type	Description	Default
plugin_type	PluginType	The category of the plugin (e.g., "backend", "sampler").	required
method	str	The name of the method to check, potentially prefixed with the plugin name and a slash (/).	required

Returns:

Type	Description
str | None	The name of a matching plugin supporting the specified method, or None.

ropt.plugins.manager.PluginType module-attribute

PluginType = Literal[
    "backend",
    "sampler",
    "realization_filter",
    "function_estimator",
    "variable_transform",
    "objective_transform",
    "nonlinear_constraint_transform",
]

Represents the valid types of plugins supported by ropt.

This type alias defines the string identifiers used to categorize different plugins within the ropt framework.