# Multi-Source Inputs¶

On occasion it is useful to allow multiple source to feed an input, creating an n-to-one relationship (publications to input). This could occur in situations like a summing junction, or a switch that can be turned on or off from multiple other federates. Alternatively, a multi-source input can be a convenient way to collecting multiple inputs into a vector for processing by the federate. While technically supported prior to 2.5.1 the control and access to this feature of HELICS was not well thought through or straightforward. The developments in 2.5.1 made it possible to specify a mathematical reduce operation on multiple inputs to allow access to them as a single value or vector.

## Mechanics of multi-input handling¶

Internally, HELICS manages input data in a queue and when a federate is granted a time, the values are read and placed in a holding location by source. In many cases there is likely only to be a single source. But if multiple publications link to a single source the results are placed in a vector. The order in that vector is by order of linking when the federate with the multi-source input is created. If a single publication value is retrieved from the input, the newest value is given as if it were a single source. In case of ties (multiple publishing federates publishing values on the same timestep), the publication that connected first is given priority.

## Controlling the behavior¶

A few flags are available to control or modify this behavior including limiting the number of connections and adjusting the priority of the different inputs sources. The behavior of inputs is controlled via flags using helicsInputSetOption() method.

### The number of connections¶

There are several flags and handle options which can control this for Inputs

• helics_handle_option_single_connection_only : If set to true specified that an input may have only 1 connection
• helics_handle_option_multiple_connections_allowed: if set to true then multiple connections are allowed
• helics_handle_option_connections: takes an integer number of connections specifying that an input must have N number of connections or an error will be generated.

### Controlling priority¶

The default priority of the inputs if they are published at the same time and only a single value is retrieved is in order of connection. This may not be desired so a few handle options are available to manipulate it.

• helics_handle_option_input_priority_location takes a value specifying the input source index to give priority to. If given multiple times it establishes an ordering of the inputs. So in the case of timing ties they can be ordered. For example if the option is called first with a given value of 2 then again with 1 and an input has 3 sources. If they all tie the source with index 1 will have highest priority, and in the case of a tie between sources 0 and 2, source 2 will have priority.
• helics_handle_option_clear_priority_list will erase the existing priority list.

## Reduction operations on multiple inputs¶

The priority of the inputs is only applicable if the default operation to retrieve a single value is used. The option helics_handle_option_multi_input_handling_method can be used to specify a reduction operation on all the inputs to process them in some fashion a number of operations are available.

The handling method specifies how the reduction operation occurs the value can then retrieved normally via any of the getValue methods on an input.

## Configuration¶

Multi Input handling can be configured through the programming API or through a file based configuration.

C++

auto& in1 = vFed1->registerInput<double>("");
in1.setOption(helics::defs::options::multi_input_handling_method,
helics::multi_input_handling_method::average);


C

/*errors are ignored here*/
helics_input in1 = helicsFederateRegisterInput("",helics_data_type_double,"",nullptr);
helicsInputSetOption(in1,helics_handle_option_multi_input_handling_method,helics_multi_input_average_operation, nullptr);


Python

in1 = h.helicsFederateRegisterInput("",h.helics_data_type_double,"");
h.helicsInputSetOption(in1,helics_handle_option_multi_input_handling_method,helics_multi_input_average_operation);


The handling can also be configured in the configuration file for the federate

TOML

inputs=[
{key="ipt2",  type="double", targets=["pub1","pub2"], connections=2, multi_input_handling_method="average"}
]


JSON

"inputs": [
{
"key": "ipt2",
"type": "double",
"connections":2,
"multi_input_handling_method":"average",
"targets": ["pub1","pub2"]
}
]


The priority of the inputs in most cases determined by the order of adding the publications as a target. This is not strictly guaranteed to occur but is a general rule and only applies in the default case, and possibly the diff operation.

## Example¶

An explanation of a full co-simulation example showing how a multi-source input might be used in a federation is provided in the HELICS Examples repository.