Plugin Manager

The PluginManager discovers plugins registered through Python entry points and looks them up by method name. A lookup returns the plugin class itself, which is called with the configuration object for its area to build the component.

The module-level get_plugin and get_plugin_name functions do the same lookups against one shared manager, created on first use. Every optimization resolves against that manager and no other, so it is the one a plugin has to be registered with to have any effect.

Plugins are normally installed, and found through their entry points. One that cannot be, such as a class defined in a script or a notebook, is added to the shared manager with register_plugin.

See Writing a Plugin for how to implement and register one.

ropt.plugins.MethodSpec module-attribute

MethodSpec: TypeAlias = (
    AbstractSet[str] | Callable[[str], bool]
)

How a plugin declares the methods it provides.

Either a set of method names, which the registry matches case-insensitively, or a predicate for the plugins that cannot enumerate what they support and must decide per name. A predicate receives the name verbatim, so it owns its own casing, and it cannot be listed. A plugin that has a default method lists "default" in its set; nothing is added on its behalf, since not every plugin has one.

ropt.plugins.manager.PluginManager

Manages the discovery and retrieval of ropt plugins.

On initialization, scans the ropt.plugins.* entry-point groups (for example ropt.plugins.backend) and registers what it finds, alongside the plugins built into ropt. Retrieve a plugin class with get_plugin, or just its name with get_plugin_name.

A third-party plugin registers itself under the relevant group in its own pyproject.toml, for example:

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

A plugin that is not installed, for instance one defined in a script or a notebook, is added with register_plugin.

__init__

__init__() -> None

Initialize the plugin manager.

register_plugin

register_plugin(
    plugin_type: PluginType, name: str, plugin: type[Any]
) -> None

Register a plugin that is not installed.

For a plugin defined where an entry point cannot reach it, such as a script or a notebook. Registering is otherwise equivalent to installing: the plugin is found by the same lookups, under the same rules, and plugin must subclass the base class of its area just the same. It must declare the methods it provides, as an installed plugin does.

Registering the name of an installed plugin is an error; installed plugins cannot be shadowed. Registering a name that was registered before replaces it, and takes effect for every lookup that follows, including one made while an optimization is running.

Parameters:

Name	Type	Description	Default
plugin_type	PluginType	The category of the plugin (for example "backend").	required
name	str	The name to register the plugin under.	required
plugin	type[Any]	The class to register.	required

Raises:

Type	Description
ValueError	If name is the name of an installed plugin.

get_plugin

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

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

method is either "plugin-name/method-name" to request a specific plugin, or just "method-name" to search discoverable plugins of plugin_type for one that supports it (preferring the default plugin).

Parameters:

Name	Type	Description	Default
plugin_type	PluginType	The category of the plugin (for example "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
type[Any]	The class of the plugin 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.

Useful for checking availability before calling get_plugin, which takes method in the same two forms ("plugin-name/method-name" or just "method-name").

Parameters:

Name	Type	Description	Default
plugin_type	PluginType	The category of the plugin (for example "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",
]

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.

ropt.plugins.manager.get_plugin

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

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

Uses a lazily created, module-level PluginManager; see PluginManager.get_plugin for the argument format.

Parameters:

Name	Type	Description	Default
plugin_type	PluginType	The category of the plugin (for example "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
type[Any]	The class of the plugin that matches the criteria.

ropt.plugins.manager.get_plugin_name

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

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

Uses a lazily created, module-level PluginManager; see PluginManager.get_plugin_name for the argument format.

Parameters:

Name	Type	Description	Default
plugin_type	PluginType	The category of the plugin (for example "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.register_plugin

register_plugin(
    plugin_type: PluginType, name: str, plugin: type[Any]
) -> None

Register a plugin that is not installed.

Adds the plugin to the lazily created, module-level PluginManager that optimize() and evaluate() resolve against, so a plugin registered here is available to every workflow started afterwards. See PluginManager.register_plugin for the rules.

Parameters:

Name	Type	Description	Default
plugin_type	PluginType	The category of the plugin (for example "backend").	required
name	str	The name to register the plugin under.	required
plugin	type[Any]	The class to register.	required