Aggregating Input Ports

By default, each input port accepts one incoming connection. Use aggregating_input_port() when several upstream outputs should feed the same input (for example summing branch currents at a node, averaging redundant temperature sensors, or applying custom combine logic).

Fan-out vs fan-in

Pattern	Supported today	How
Fan-out	Yes	One output → many inputs (connect the same source port to multiple targets)
Fan-in	Yes, on aggregating ports	Many outputs → one input (declare `aggregating_input_port()` on the target)

Regular input_port() ports still raise DuplicateConnectionError if you connect a second source.

Built-in aggregation

from hardwave import Component, ComponentMeta, ComponentRegistry
from hardwave.ports import aggregating_input_port, output_port, PortAggregation

class CurrentSumNode(Component):
    meta = ComponentMeta(
        name="CurrentSumNode",
        display_name="Current Sum Node",
        version="1.0.0",
        description="Sums all incoming branch currents",
        docs="",
        category="Electrical",
    )
    ports = [
        aggregating_input_port(
            "current_in",
            "Current",
            aggregation=PortAggregation.SUM,
            description="Total current from all connected branches",
        ),
        output_port("total_current", "Current", "Net current into the node"),
    ]
    parameters = []

    def solve(self, inputs: dict) -> dict:
        return {"total_current": inputs["current_in"]}

ComponentRegistry.instance().register(CurrentSumNode)

Built-in modes

`PortAggregation`	Behaviour
`SUM`	Add all values
`MEAN`	Arithmetic mean
`MIN` / `MAX`	Minimum / maximum
`PRODUCT`	Multiply all values
`FIRST` / `LAST`	First or last value (connection order)
`CUSTOM`	Set automatically when you pass `aggregate=`

Optional limits:

aggregating_input_port(
    "current_in",
    "Current",
    aggregation=PortAggregation.SUM,
    min_connections=2,   # validation error if fewer wires (unless external input)
    max_connections=4,   # raises MaxConnectionsExceededError at connect time
)

Custom aggregation (callable wins entirely)

Pass an aggregate callable to fully control how values are combined. When present, it replaces any built-in aggregation mode. The engine passes the raw list of upstream values to your function.

from hardwave.ports import aggregating_input_port

def signed_current_sum(values, component, port):
    return sum(values)

def abs_mean(values, component, port):
    return sum(abs(v) for v in values) / len(values)

ports = [
    aggregating_input_port("current_in", "Current", aggregate=signed_current_sum),
]

Aggregator signature

def my_aggregator(
    values: list,       # upstream values in connection order
    component: Component,
    port: Port,
) -> Any:
    ...

The return value is what solve(inputs) receives under port.name: always a single value, never a list.

Wiring a graph

from hardwave.simulation import SimulationGraph, SimulationEngine
from hardwave.stdlib.components.passive import CurrentSource

graph = SimulationGraph()
graph.add_component(CurrentSource("src_a", param_values={"current": 1.0}))
graph.add_component(CurrentSource("src_b", param_values={"current": 2.5}))
graph.add_component(CurrentSumNode("node"))

graph.connect("src_a", "current_out", "node", "current_in")
graph.connect("src_b", "current_out", "node", "current_in")  # second wire: OK on aggregating ports

graph.validate()
result = SimulationEngine(graph).run(inputs={})
print(result.get_output("node", "total_current"))  # 3.5

Disconnecting one source

# Remove all connections to a port
graph.disconnect("node", "current_in")

# Remove one specific source
graph.disconnect("node", "current_in", "src_a", "current_out")

# Inspect incoming connections
graph.connections_to("node", "current_in")

Serialization

Port.to_dict() serializes the aggregation mode ("sum", "custom", etc.) but not the callable. Custom functions live on the component class at definition time (the same pattern as solve()). When you deserialize a graph with SimulationGraph.from_dict(), the registered component class supplies aggregation_fn.

Composite components

Internal sub-graphs use the same aggregation rules. If two internal connections target the same aggregating input port, values are combined before the sub-component’s solver runs.

Error	Cause
`DuplicateConnectionError`	Second wire to a regular `input_port()`
`MaxConnectionsExceededError`	More connections than `max_connections`
`INSUFFICIENT_CONNECTIONS`	Fewer wires than `min_connections` at validation
`PortConfigurationError`	`CUSTOM` aggregation declared without `aggregate=` at registration

Getting Started

Guides

Simulation

Reference

Aggregating Input Ports

Fan-out vs fan-in

Built-in aggregation

Built-in modes

Custom aggregation (callable wins entirely)

Aggregator signature

Wiring a graph

Disconnecting one source

Serialization

Composite components

​Fan-out vs fan-in

​Built-in aggregation

​Built-in modes

​Custom aggregation (callable wins entirely)

​Aggregator signature

​Wiring a graph

​Disconnecting one source

​Serialization

​Composite components

​Related errors

Fan-out vs fan-in

Built-in aggregation

Built-in modes

Custom aggregation (callable wins entirely)

Aggregator signature

Wiring a graph

Disconnecting one source

Serialization

Composite components

Related errors