Episode 2: Ports and Events
Declare a node’s ports by name, let start() check that the inputs can be combined, and add an asynchronous output that carries a value only when something happens.
A node can have as many inputs and outputs as it needs, each a port it declares by name. Every input contributes one frame to each step, so the pipeline checks at start() that the inputs can be combined. An output can also be asynchronous, carrying a value only when something happens. Crossings subtracts a reference from a signal and emits the difference; a second output emits one value each time the difference rises through a level, a decision leaving the signal path.
input_ports and output_ports are lists of gp.IPort.Configuration and gp.OPort.Configuration, each with a name, passed to the base class. Take them from kwargs when they are there: a node loaded from a saved pipeline is handed its ports back that way. The second output is declared with timing=ASYNC.
16class Crossings(gp.IONode):
17 """Signal minus reference, and an event at each rising crossing."""
18
19 PORT_SIGNAL = "signal"
20 PORT_REFERENCE = "reference"
21 PORT_OUT = gp.Constants.Defaults.PORT_OUT
22 PORT_CROSSING = "crossing"
23
24 class Configuration(gp.IONode.Configuration):
25 class Keys(gp.IONode.Configuration.Keys):
26 LEVEL = "level"
27
28 def __init__(self, level: float = 5.0, **kwargs):
29 # Taken from kwargs when present: a node loaded from a saved
30 # pipeline is handed its ports back there.
31 input_ports = kwargs.pop(KEYS.INPUT_PORTS, [
32 gp.IPort.Configuration(name=self.PORT_SIGNAL),
33 gp.IPort.Configuration(name=self.PORT_REFERENCE),
34 ])
35 output_ports = kwargs.pop(KEYS.OUTPUT_PORTS, [
36 gp.OPort.Configuration(name=self.PORT_OUT),
37 gp.OPort.Configuration(name=self.PORT_CROSSING,
38 timing=TIMING.ASYNC),
39 ])
40 super().__init__(level=level, input_ports=input_ports,
41 output_ports=output_ports, **kwargs)
42 self._above = False
The base class refuses inputs it cannot combine, and describes every output like the combined input. The asynchronous port is then given its own context: one channel, named crossing, one value per event.
44 def setup(self, data, port_context_in):
45 # The base class refuses inputs it cannot combine, and describes
46 # every output port like the combined input.
47 port_context_out = super().setup(data, port_context_in)
48 # An event is one value, arriving whenever it happens.
49 port_context_out[self.PORT_CROSSING].update({
50 KEYS.CHANNEL_COUNT: 1,
51 KEYS.FRAME_SIZE: 1,
52 KEYS.CHANNEL_ROLES: [gp.Constants.ChannelRoles.SIGNAL],
53 KEYS.CHANNEL_LABELS: ["crossing"],
54 gp.IPort.Configuration.Keys.TIMING: TIMING.ASYNC,
55 })
56 self._above = False
57 return port_context_out
step() returns the difference on the continuous port every time, and a frame for the crossing port only when the difference rises through the level; otherwise it leaves that key out.
59 def step(self, data):
60 difference = data[self.PORT_SIGNAL] - data[self.PORT_REFERENCE]
61 mean = difference.mean(axis=1)
62 above = mean > self.config[self.Configuration.Keys.LEVEL]
63 before = np.concatenate(([self._above], above[:-1]))
64 self._above = bool(above[-1])
65
66 out = {self.PORT_OUT: difference}
67 # Most steps put nothing on the asynchronous port.
68 rising = np.flatnonzero(above & ~before)
69 if rising.size:
70 out[self.PORT_CROSSING] = mean[rising[:1], None]
71 return out
A four-channel square wave against a reference of noise, two channels wide the first time and one the second. In connect(), a port is addressed as node["reference"]; a bare node means its port named out, or in on the receiving end.
74def build(reference_channels: int) -> tuple:
75 """A 4-channel square wave against a reference of noise."""
76 p = gp.Pipeline()
77 signal = gp.Generator(sampling_rate=RATE, channel_count=4,
78 signal_frequency=0.5, signal_shape="rect",
79 signal_amplitude=10.0, noise_amplitude=1.0,
80 name="signal")
81 reference = gp.Generator(sampling_rate=RATE,
82 channel_count=reference_channels,
83 noise_amplitude=1.0, name="reference")
84 node = Crossings(level=5.0)
85 difference = gp.Collector(name="difference")
86 events = gp.Collector(name="events")
87
88 p.connect(signal, node[Crossings.PORT_SIGNAL])
89 p.connect(reference, node[Crossings.PORT_REFERENCE])
90 p.connect(node, difference)
91 p.connect(node[Crossings.PORT_CROSSING], events)
92 return p, difference, events
connect() accepts the two-channel reference, because a port’s width is only known once the node upstream has set up. The base class’s setup() then compares every input: one sampling rate, one frame size, one channel count, one payload type. Anything else is refused, naming the node, the ports and what each carried, and start() raises a RuntimeError with that message as its cause.
97 # 1. Four channels against two. connect() accepts it, because the
98 # widths are known only once the sources have set up.
99 p, _, _ = build(reference_channels=2)
100 try:
101 p.start()
102 except RuntimeError as error:
103 print(f"refused: {error.__cause__}")
104 finally:
105 p.stop()
106 p.close()
A single channel is broadcast to the others, which is why the one-channel reference is subtracted from all four. A Collector takes the timing of whatever is connected to it and stacks the events into (time, channel, event), as it stacks a Trigger’s epochs in Season 5, Episode 6; a ResultScope would show each as it arrives.
108 # 2. A one-channel reference is subtracted from all four.
109 p, difference, events = build(reference_channels=1)
110 p.start()
111 while (difference.result is None
112 or len(difference.result.data) < RATE * SECONDS):
113 time.sleep(0.05)
114 p.stop()
115 p.close()
116
117 # The square wave rises at 0, 2 and 4 s. A Collector stacks the
118 # events into (time, channel, event).
119 print(f"{SECONDS} s of difference: "
120 f"{difference.result.data.shape[1]} channels")
121 print(f"events: {events.result.data.shape}")
Run the script:
refused: All continuous ports must have the same channel count; Crossings
got signal=4, reference=2. A port carrying one channel is broadcast to the
widest port, but two different multi-channel widths cannot be combined.
Give the ports the same channel count, or select channels with a Router
before Crossings.
5 s of difference: 4 channels
events: (1, 1, 3)
The square wave rises at 0, 2 and 4 s, so five seconds give three events.
In this episode, you learned how to:
declare input and output ports by name, and address them in
connect()rely on
start()to refuse inputs that cannot be combined, and read whyadd an asynchronous output, and consume its events
Proceed to Episode 3, where the two ends of a pipeline, a source and a sink, are written.
Nodes in this episode: Generator, Collector, and the file’s own Crossings
File s7e2_ports_and_events.py – View file on GitHub
1"""Season 7, Episode 2: named ports, checked at start, and an event output."""
2
3import time
4
5import numpy as np
6
7import gpype as gp
8
9KEYS = gp.Constants.Keys
10TIMING = gp.Constants.Timing
11
12RATE = 250
13SECONDS = 5
14
15
16class Crossings(gp.IONode):
17 """Signal minus reference, and an event at each rising crossing."""
18
19 PORT_SIGNAL = "signal"
20 PORT_REFERENCE = "reference"
21 PORT_OUT = gp.Constants.Defaults.PORT_OUT
22 PORT_CROSSING = "crossing"
23
24 class Configuration(gp.IONode.Configuration):
25 class Keys(gp.IONode.Configuration.Keys):
26 LEVEL = "level"
27
28 def __init__(self, level: float = 5.0, **kwargs):
29 # Taken from kwargs when present: a node loaded from a saved
30 # pipeline is handed its ports back there.
31 input_ports = kwargs.pop(KEYS.INPUT_PORTS, [
32 gp.IPort.Configuration(name=self.PORT_SIGNAL),
33 gp.IPort.Configuration(name=self.PORT_REFERENCE),
34 ])
35 output_ports = kwargs.pop(KEYS.OUTPUT_PORTS, [
36 gp.OPort.Configuration(name=self.PORT_OUT),
37 gp.OPort.Configuration(name=self.PORT_CROSSING,
38 timing=TIMING.ASYNC),
39 ])
40 super().__init__(level=level, input_ports=input_ports,
41 output_ports=output_ports, **kwargs)
42 self._above = False
43
44 def setup(self, data, port_context_in):
45 # The base class refuses inputs it cannot combine, and describes
46 # every output port like the combined input.
47 port_context_out = super().setup(data, port_context_in)
48 # An event is one value, arriving whenever it happens.
49 port_context_out[self.PORT_CROSSING].update({
50 KEYS.CHANNEL_COUNT: 1,
51 KEYS.FRAME_SIZE: 1,
52 KEYS.CHANNEL_ROLES: [gp.Constants.ChannelRoles.SIGNAL],
53 KEYS.CHANNEL_LABELS: ["crossing"],
54 gp.IPort.Configuration.Keys.TIMING: TIMING.ASYNC,
55 })
56 self._above = False
57 return port_context_out
58
59 def step(self, data):
60 difference = data[self.PORT_SIGNAL] - data[self.PORT_REFERENCE]
61 mean = difference.mean(axis=1)
62 above = mean > self.config[self.Configuration.Keys.LEVEL]
63 before = np.concatenate(([self._above], above[:-1]))
64 self._above = bool(above[-1])
65
66 out = {self.PORT_OUT: difference}
67 # Most steps put nothing on the asynchronous port.
68 rising = np.flatnonzero(above & ~before)
69 if rising.size:
70 out[self.PORT_CROSSING] = mean[rising[:1], None]
71 return out
72
73
74def build(reference_channels: int) -> tuple:
75 """A 4-channel square wave against a reference of noise."""
76 p = gp.Pipeline()
77 signal = gp.Generator(sampling_rate=RATE, channel_count=4,
78 signal_frequency=0.5, signal_shape="rect",
79 signal_amplitude=10.0, noise_amplitude=1.0,
80 name="signal")
81 reference = gp.Generator(sampling_rate=RATE,
82 channel_count=reference_channels,
83 noise_amplitude=1.0, name="reference")
84 node = Crossings(level=5.0)
85 difference = gp.Collector(name="difference")
86 events = gp.Collector(name="events")
87
88 p.connect(signal, node[Crossings.PORT_SIGNAL])
89 p.connect(reference, node[Crossings.PORT_REFERENCE])
90 p.connect(node, difference)
91 p.connect(node[Crossings.PORT_CROSSING], events)
92 return p, difference, events
93
94
95if __name__ == "__main__":
96
97 # 1. Four channels against two. connect() accepts it, because the
98 # widths are known only once the sources have set up.
99 p, _, _ = build(reference_channels=2)
100 try:
101 p.start()
102 except RuntimeError as error:
103 print(f"refused: {error.__cause__}")
104 finally:
105 p.stop()
106 p.close()
107
108 # 2. A one-channel reference is subtracted from all four.
109 p, difference, events = build(reference_channels=1)
110 p.start()
111 while (difference.result is None
112 or len(difference.result.data) < RATE * SECONDS):
113 time.sleep(0.05)
114 p.stop()
115 p.close()
116
117 # The square wave rises at 0, 2 and 4 s. A Collector stacks the
118 # events into (time, channel, event).
119 print(f"{SECONDS} s of difference: "
120 f"{difference.result.data.shape[1]} channels")
121 print(f"events: {events.result.data.shape}")