ChannelMap#

class ChannelMap(
channels: dict[str,
str | None]=<factory>,
include_unmapped: bool = False,
instrument: str | None = None,
)[source]#

Bases: object

Which pymeasure properties publish, and under which channel names.

Generate one from an instrument, save it, edit the channel of each entry (or set it to null to stop publishing that property), and pass the file or object to PymeasureInstrument or attach.

A command channel is the mapped name plus .cmd; a measurement channel is the mapped name. Both sit under the instrument name: <instrument name>.<mapped name>[.cmd].

Variables:

  • channels (dict[str, str | None]) – Attribute path ("ch_1.voltage_setpoint") to channel name ("ch1.vset"), or None to leave that property unpublished.

  • include_unmapped (bool) – Publish properties missing from channels under their default names.

  • instrument (str | None) – module.Class of the instrument the map was generated from; informational.

channels: dict[str, str | None]#
include_unmapped: bool = False#
instrument: str | None = None#
classmethod defaults() → ChannelMap[source]#

Return the map used when none is given: every property under its default name.

classmethod generate(
target: CommonBase | type[CommonBase],
) → ChannelMap[source]#

Build a map listing every publishable property of target under its default name.

Parameters:

target

A pymeasure instrument instance (preferred: it sees channels added in __init__) or class.

Returns:

A ChannelMap with one entry per property and include_unmapped=False.

classmethod from_dict(
data: dict[str, Any],
) → ChannelMap[source]#

Parse the JSON-compatible form written by to_dict.

Each channels value may be a channel-name string, null, or an object whose channel key holds either; its kind/get/set/doc keys are informational.

Raises:

ValueError – The format tag is unknown or an entry is malformed.

classmethod load(
path: str | Path,
) → ChannelMap[source]#

Read a map from a JSON file written by save (or the instro pymeasure map command).

to_dict(
specs: list[ChannelSpec] | None = None,
) → dict[str, Any][source]#

Return the JSON-compatible form.

Parameters:

specs

Inspection results for the instrument. When given, each entry also records the property’s kind, SCPI commands, and docstring to make the file easier to edit.

save(
path: str | Path,
target: CommonBase | type[CommonBase] | None = None,
) → None[source]#

Write the map as JSON.

Parameters:

  • path

    Destination file.

  • target

    Instrument the map belongs to; when given, entries carry each property’s kind, SCPI commands, and docstring.

rename(
names: dict[str, str | None],
) → ChannelMap[source]#

Set the channel name of each attribute path in names (None stops publishing it).

Example:

channel_map.rename({"ch_1.voltage_setpoint": "out1.v_set", "ch_1.current": "out1.i"})
Returns:

This map, so calls can be chained.

Raises:

KeyError – A path is not in the map.

exclude(
*patterns: str,
) → ChannelMap[source]#

Stop publishing every attribute path that matches one of the glob patterns.

Example:

channel_map.exclude("ch_2.*", "ch_3.*")
Returns:

This map, so calls can be chained.

Raises:

KeyError – A pattern matches no path, which is usually a typo.

select(
*patterns: str,
) → ChannelMap[source]#

Stop publishing every attribute path that matches none of the glob patterns.

Example:

channel_map.select("ch_1.*")  # publish output 1 only
Returns:

This map, so calls can be chained.

Raises:

KeyError – A pattern matches no path, which is usually a typo.

preview(
target: CommonBase | type[CommonBase],
name: str | None = None,
) → list[dict[str, str | None]][source]#

Show exactly which channels each property publishes, separately for commands and measurements.

Writing a property publishes a Command on the command channel; reading it publishes a Measurement on the measurement channel. A control has both, a measurement only the second, a setting only the first.

Example:

import pandas as pd
pd.DataFrame(channel_map.preview(supply, "psu"))
Parameters:

  • target

    The instrument (instance or class) the map is for.

  • name

    Instrument name to prefix, as passed to attach or PymeasureInstrument.

Returns:

One row per property with keys property, kind, command, and measurement; a channel is None when the property doesn’t publish in that direction.

Raises:

ValueError – The map does not fit target (see resolve).

resolve(
specs: list[ChannelSpec],
) → dict[str, str][source]#

Return attribute path to channel name for every property that publishes.

Parameters:

specs

Inspection results for the instrument the map is applied to.

Raises:

ValueError – The map names a path the instrument does not have (a typo, or a pymeasure upgrade renamed it), a channel name is invalid or ends in .cmd, or two properties map to the same channel name.