Compound

This module contains classes to create compound tools.

The distinction between Compound, Ensemble, Combined and Multichannel tools is presented in the table below:

Class	Device(s)	Components
Compound	Multiple connection	Different parts
Ensemble	Multiple connection	Duplicate parts
Combined	Single connection	Different parts
Multichannel	Single connection	Duplicate parts

CLASS	DESCRIPTION
Part	Protocol for Part (i.e. component tools)
Compound	Compound class is an aggregation of multiple part tools
Ensemble	Ensemble class is an aggregation of duplicate part tools to form multiple channels
Combined	Combined class is an composition of multiple part tools
Multichannel	Multichannel class is an composition of duplicate part tools to form multiple channels

Documentation last updated: 2025-06-11

Combined

Combined(
    *args,
    parts: dict[str, Part],
    verbose: bool = False,
    **kwargs,
)

Combined class is an composition of multiple part tools. Do not instantiate this class directly. Subclass this class to create a specific Combined tool.

Constructor:

parts (dict[str,Part]): dictionary of parts
verbose (bool, optional): verbosity of class. Defaults to False.

ATTRIBUTE	DESCRIPTION
device	device object TYPE: Device
connection_details	connection details for the device TYPE: dict
parts	namespace of parts TYPE: SimpleNamespace[str, Part]
flags	flags of class TYPE: SimpleNamespace[str, bool]
is_busy	whether any part is busy TYPE: bool
is_connected	whether all parts are connected TYPE: bool
verbose	verbosity of class TYPE: bool

METHOD	DESCRIPTION
fromConfig	factory method to create Combined from configuration dictionary
connect	connect to the device
disconnect	disconnect from the device
resetFlags	reset all flags to class attribute _default_flags
shutdown	shutdown the device

Initialise Combined class

PARAMETER	DESCRIPTION
parts	dictionary of parts TYPE: dict[str, Part]
verbose	verbosity of class. Defaults to False. TYPE: bool DEFAULT: False

connection_details property

connection_details

Connection details for the device

is_busy property

is_busy

Whether any part is busy

is_connected property

is_connected: bool

Whether all parts are connected

parts property

parts: SimpleNamespace[str, Part]

Namespace of parts

verbose property writable

verbose: bool

Verbosity of class

connect

connect()

Connect to the device

disconnect

disconnect()

Disconnect from the device

fromConfig classmethod

fromConfig(config: dict) -> Type[Combined]

Factory method to create Combined from configuration dictionary

PARAMETER	DESCRIPTION
config	configuration dictionary TYPE: dict

RETURNS	DESCRIPTION
Type[Combined]	Type[Combined]: instance of Combined (or its subclasses)

resetFlags

resetFlags()

Reset all flags to class attribute _default_flags

shutdown

shutdown()

Shutdown the device

Compound

Compound(
    *args,
    parts: dict[str, Part],
    verbose: bool = False,
    **kwargs,
)

Compound class is an aggregation of multiple part tools. Do not instantiate this class directly. Subclass this class to create a specific Compound tool.

Constructor:

parts (dict[str,Part]): dictionary of parts
verbose (bool, optional): verbosity of class. Defaults to False.

ATTRIBUTE	DESCRIPTION
connection_details	connection details of each part TYPE: dict
parts	namespace of parts TYPE: SimpleNamespace[str, Part]
flags	flags of class TYPE: SimpleNamespace[str, bool]
is_busy	whether any part is busy TYPE: bool
is_connected	whether all parts are connected TYPE: bool
verbose	verbosity of class TYPE: bool

METHOD	DESCRIPTION
fromConfig	factory method to create Compound from configuration dictionary
connect	connect to each component Part
disconnect	disconnect from each component Part
resetFlags	reset all flags to class attribute _default_flags
shutdown	shutdown each component Part

Initialise Compound class

PARAMETER	DESCRIPTION
parts	dictionary of parts TYPE: dict[str, Part]
verbose	verbosity of class. Defaults to False. TYPE: bool DEFAULT: False

connection_details property

connection_details

Connection details of each part

is_busy property

is_busy

Whether any part is busy

is_connected property

is_connected

Whether all parts are connected

parts property

parts: SimpleNamespace[str, Part]

Namespace of parts

verbose property writable

verbose: bool

Verbosity of class

connect

connect()

Connect to each component Part

disconnect

disconnect()

Disconnect from each component Part

fromConfig classmethod

fromConfig(config: dict) -> Compound

Factory method to create Compound from configuration dictionary

PARAMETER	DESCRIPTION
config	configuration dictionary TYPE: dict

RETURNS	DESCRIPTION
Compound	instance of Compound (or its subclasses) TYPE: Compound

resetFlags

resetFlags()

Reset all flags to class attribute _default_flags

shutdown

shutdown()

Shutdown each component Part

Ensemble

Ensemble(
    channels: Sequence[int] | None = None,
    details: dict | Sequence[dict] | None = None,
    *args,
    parts: dict[str, Part] | None = None,
    verbose: bool = False,
    **kwargs,
)

Bases: Compound

Ensemble class is an aggregation of duplicate part tools to form multiple channels. Do not instantiate this class directly. Use the factory method to generate the desired class first.

Constructor:

channels (Sequence[int] | None, optional): sequence of channels. Defaults to None.
details (dict | Sequence[dict] | None, optional): dictionary or sequence of dictionaries of part details. Defaults to None.
parts (dict[str,Part] | None, optional): dictionary of parts. Defaults to None.
verbose (bool, optional): verbosity of class. Defaults to False.

ATTRIBUTE	DESCRIPTION
channels	dictionary of channels TYPE: dict[int, Part]
connection_details	connection details of each part TYPE: dict
parts	namespace of parts TYPE: SimpleNamespace[str, Part]
flags	flags of class TYPE: SimpleNamespace[str, bool]
is_busy	whether any part is busy TYPE: bool
is_connected	whether all parts are connected TYPE: bool
verbose	verbosity of class TYPE: bool

METHOD	DESCRIPTION
createParts	factory method to instantiate Ensemble from channels and part details
factory	factory method to generate Ensemble class from parent class
fromConfig	factory method to create Compound from configuration dictionary
parallel	execute function in parallel on all channels
connect	connect to each component Part in parallel
disconnect	disconnect from each component Part
resetFlags	reset all flags to class attribute _default_flags
shutdown	shutdown each component Part

Initialise Ensemble class

PARAMETER	DESCRIPTION
channels	sequence of channels TYPE: Sequence[int] DEFAULT: None
details	dictionary or sequence of dictionaries of part details TYPE: dict | Sequence[dict] DEFAULT: None
parts	dictionary of parts TYPE: dict[str, Part] DEFAULT: None
verbose	verbosity of class. Defaults to False. TYPE: bool DEFAULT: False

channels property

channels: dict[int, Part]

Dictionary of channels

connect

connect()

Connect to each component Part in parallel

createParts classmethod

createParts(
    channels: Sequence[int],
    details: dict | Sequence[dict],
    *args,
    **kwargs,
) -> dict[str, Part]

Factory method to instantiate Ensemble from channels and part details

PARAMETER	DESCRIPTION
channels	sequence of channels TYPE: Sequence[int]
details	dictionary or sequence of dictionaries of part details TYPE: dict | Sequence[dict]

RETURNS	DESCRIPTION
dict[str, Part]	dict[str,Part]: dictionary of parts

factory classmethod

factory(parent: type) -> Type[Ensemble]

Factory method to generate Ensemble class from parent class

PARAMETER	DESCRIPTION
parent	parent class TYPE: type

RETURNS	DESCRIPTION
Type[Ensemble]	Type[Ensemble]: subclass of Ensemble class

fromConfig classmethod

fromConfig(config: dict) -> Ensemble

Factory method to create Compound from configuration dictionary

PARAMETER	DESCRIPTION
config	configuration dictionary TYPE: dict

RETURNS	DESCRIPTION
Ensemble	instance of Compound (or its subclasses) TYPE: Ensemble

parallel

parallel(
    method_name: str,
    kwargs_generator: Callable[
        [int, int, Part], dict[str, Any]
    ]
    | None = None,
    *args,
    channels: Iterable[int],
    max_workers: int = 4,
    timeout: int | float = 120,
    stagger: int | float = 0.5,
    **kwargs,
) -> dict[int, Any]

Execute function in parallel on all channels

PARAMETER	DESCRIPTION
method_name	method name to be executed TYPE: str
kwargs_generator	function to generate kwargs for each channel. Defaults to None. TYPE: Callable[[int, int, Part], dict[str, Any]] | None DEFAULT: None
channels	channels to execute on TYPE: Iterable[int]
max_workers	maximum number of workers. Defaults to 4. TYPE: int DEFAULT: 4
timeout	timeout for each worker. Defaults to 120. TYPE: int | float DEFAULT: 120
stagger	time to wait between each worker. Defaults to 0.5. TYPE: int | float DEFAULT: 0.5

RETURNS	DESCRIPTION
dict[int, Any]	dict[int,Any]: dictionary of outputs

Multichannel

Multichannel(
    channels: Sequence[int] | None = None,
    details: dict | Sequence[dict] | None = None,
    *args,
    parts: dict[str, Part] | None = None,
    verbose: bool = False,
    **kwargs,
)

Bases: Combined

Multichannel class is an composition of duplicate part tools to form multiple channels.

Constructor:

channels (Sequence[int] | None, optional): sequence of channels. Defaults to None.
details (dict | Sequence[dict] | None, optional): dictionary or sequence of dictionaries of part details. Defaults to None.
parts (dict[str,Part] | None, optional): dictionary of parts. Defaults to None.
verbose (bool, optional): verbosity of class. Defaults to False.

ATTRIBUTE	DESCRIPTION
channels	dictionary of channels TYPE: dict[int, Part]
device	device object TYPE: Device
connection_details	connection details for the device TYPE: dict
parts	namespace of parts TYPE: SimpleNamespace[str, Part]
flags	flags of class TYPE: SimpleNamespace[str, bool]
is_busy	whether any part is busy TYPE: bool
is_connected	whether all parts are connected TYPE: bool
verbose	verbosity of class TYPE: bool

METHOD	DESCRIPTION
createParts	factory method to instantiate Multichannel from channels and part details
factory	factory method to generate Multichannel class from parent class
fromConfig	factory method to create Combined from configuration dictionary
setActiveChannel	set active channel
connect	connect to the device
disconnect	disconnect from the device
resetFlags	reset all flags to class attribute _default_flags
shutdown	shutdown the device

Initialise Multichannel class

PARAMETER	DESCRIPTION
channels	sequence of channels. Defaults to None. TYPE: Sequence[int] | None DEFAULT: None
details	dictionary or sequence of dictionaries of part details. DEfaults to None. TYPE: dict | Sequence[dict] | None DEFAULT: None
parts	dictionary of parts. Defaults to None. TYPE: dict[str, Part] | None DEFAULT: None
verbose	verbosity of class. Defaults to False. TYPE: bool DEFAULT: False

channel property writable

channel: int

Active channel

channels property

channels: dict[int, Part]

Dictionary of channels

createParts classmethod

createParts(
    channels: Sequence[int],
    details: dict | Sequence[dict] | None,
    *args,
    **kwargs,
) -> tuple[dict[str, Part], Device]

Factory method to instantiate Multichannel from channels and part details

PARAMETER	DESCRIPTION
channels	sequence of channels TYPE: Sequence[int]
details	dictionary or sequence of dictionaries of part details TYPE: dict | Sequence[dict] | None

RETURNS	DESCRIPTION
tuple[dict[str, Part], Device]	tuple[dict[str,Part],Device]: dictionary of parts and device

factory classmethod

factory(parent: type) -> Type[Multichannel]

Factory method to generate Multichannel class from parent

PARAMETER	DESCRIPTION
parent	parent class TYPE: type

RETURNS	DESCRIPTION
Type[Multichannel]	Type[Multichannel]: subclass of Multichannel class

fromConfig classmethod

fromConfig(config: dict) -> Multichannel

Factory method to create Compound from configuration dictionary

PARAMETER	DESCRIPTION
config	configuration dictionary TYPE: dict

RETURNS	DESCRIPTION
Multichannel	instance of Compound (or its subclasses) TYPE: Multichannel

setActiveChannel

setActiveChannel(channel: int | None = None)

Set active channel

PARAMETER	DESCRIPTION
channel	select channel. Defaults to None. TYPE: int | None DEFAULT: None

Part

Bases: Protocol

Protocol for Part (i.e. component tools)

connect

connect()

Connect to the device

disconnect

disconnect()

Disconnect from the device

resetFlags

resetFlags()

Reset all flags to class attribute _default_flags

shutdown

shutdown()

Shutdown the device