Plugin Manager

ropt.plugins

Plugin discovery and registration.

A PluginManager finds plugins through their entry points and looks them up by method name, returning the class, which is called with the configuration object of its area to build the component. get_plugin and get_plugin_name do the same lookups against one shared manager, created on first use; every optimization resolves against that manager, so it is the one register_plugin has to add to for a plugin that cannot be installed. See Writing a Plugin.

ropt.plugins.MethodSpec

MethodSpec = Set[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.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; see Registering it. 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.	required

Returns:

Type	Description
type[Any]	The class of the plugin that matches the criteria.

Raises:

Type	Description
ValueError	If no plugin of that type supports the method.

get_plugin_name

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

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

Reports whether a method is available without retrieving its class. method takes the same two forms as get_plugin ("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.	required

Returns:

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

ropt.plugins.PluginType module-attribute

PluginType = Literal[
    "backend",
    "sampler",
    "realization_filter",
    "function_estimator",
]

The plugin areas a method string can select from.

ropt.plugins.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.	required

Returns:

Type	Description
type[Any]	The class of the plugin that matches the criteria.

ropt.plugins.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.	required

Returns:

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

ropt.plugins.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