C API Reference

Enum

enumerator helics_core_type_default

a default core type that will default to something available

enumerator helics_core_type_http

a core type using http for communication

enumerator helics_core_type_inproc

an in process core type for handling communications in shared memory it is pretty similar to the test core but stripped from the “test” components

enumerator helics_core_type_interprocess

interprocess uses memory mapped files to transfer data (for use when all federates are on the same machine

enumerator helics_core_type_ipc

interprocess uses memory mapped files to transfer data (for use when all federates are on the same machine ipc is the same as /ref helics_core_type_interprocess

enumerator helics_core_type_mpi

use MPI for operation on a parallel cluster

enumerator helics_core_type_nng

for using the nanomsg communications

enumerator helics_core_type_null

an explicit core type that is recognized but explicitly doesn’t exist, for testing and a few other assorted reasons

enumerator helics_core_type_tcp

use a generic TCP protocol message stream to send messages

enumerator helics_core_type_tcp_ss

a single socket version of the TCP core for more easily handling firewalls

enumerator helics_core_type_test

use the Test core if all federates are in the same process

enumerator helics_core_type_udp

use UDP packets to send the data

enumerator helics_core_type_websocket

a core using websockets for communication

enumerator helics_core_type_zmq

use the Zero MQ networking protocol

enumerator helics_core_type_zmq_test

single socket version of ZMQ core usually for high fed count on the same system

enumerator helics_data_type_any

open type that can be anything

enumerator helics_data_type_boolean

a boolean data type

enumerator helics_data_type_complex

a pair of doubles representing a complex number

enumerator helics_data_type_complex_vector

a complex vector object

enumerator helics_data_type_double

a double precision floating point number

enumerator helics_data_type_int

a 64 bit integer

enumerator helics_data_type_named_point

a named point consisting of a string and a double

enumerator helics_data_type_raw

raw data type

enumerator helics_data_type_string

a sequence of characters

enumerator helics_data_type_time

time data type

enumerator helics_data_type_vector

an array of doubles

enumerator helics_error_connection_failure

the operation to connect has failed

enumerator helics_error_discard

the input was discarded and not used for some reason

enumerator helics_error_execution_failure

the function execution has failed

enumerator helics_error_external_type

an unknown non-helics error was produced

enumerator helics_error_fatal

global fatal error for federation

enumerator helics_error_insufficient_space

insufficient space is available to store requested data

enumerator helics_error_invalid_argument

the parameter passed was invalid and unable to be used

enumerator helics_error_invalid_function_call

the call made was invalid in the present state of the calling object

enumerator helics_error_invalid_object

indicator that the object used was not a valid object

enumerator helics_error_invalid_state_transition

error issued when an invalid state transition occurred

enumerator helics_error_other

the function produced a helics error of some other type

enumerator helics_error_registration_failure

registration has failed

enumerator helics_error_system_failure

the federate has terminated unexpectedly and the call cannot be completed

enumerator helics_filter_type_clone

a filter type that duplicates a message and sends the copy to a different destination

enumerator helics_filter_type_custom

a custom filter type that executes a user defined callback

enumerator helics_filter_type_delay

a filter type that executes a fixed delay on a message

enumerator helics_filter_type_firewall

a customizable filter type that can perform different actions on a message based on firewall like rules

enumerator helics_filter_type_random_delay

a filter type that executes a random delay on the messages

enumerator helics_filter_type_random_drop

a filter type that randomly drops messages

enumerator helics_filter_type_reroute

a filter type that reroutes a message to a different destination than originally specified

enumerator helics_flag_delay_init_entry

used to delay a core from entering initialization mode even if it would otherwise be ready

enumerator helics_flag_enable_init_entry

used to clear the HELICS_DELAY_INIT_ENTRY flag in cores

enumerator helics_flag_forward_compute

flag indicating that a federate performs forward computation and does internal rollback

enumerator helics_flag_ignore_time_mismatch_warnings

used to not display warnings on mismatched requested times

enumerator helics_flag_interruptible

flag indicating that a federate can be interrupted

enumerator helics_flag_observer

flag indicating that a federate is observe only

enumerator helics_flag_only_transmit_on_change

flag indicating a federate/interface should only transmit values if they have changed(binary equivalence)

enumerator helics_flag_only_update_on_change

flag indicating a federate/interface should only trigger an update if a value has changed (binary equivalence)

enumerator helics_flag_realtime

flag indicating that a federate needs to run in real time

enumerator helics_flag_restrictive_time_policy

flag indicating a federate should operate on a restrictive time policy, which disallows some 2nd order time evaluation and can be useful for certain types of dependency cycles and update patterns, but generally shouldn’t be used as it can lead to some very slow update conditions

enumerator helics_flag_rollback

flag indicating that a federate has rollback capability

enumerator helics_flag_single_thread_federate

flag indicating that the federate will only interact on a single thread

enumerator helics_flag_slow_responding

flag specifying that a federate, core, or broker may be slow to respond to pings If the federate goes offline there is no good way to detect it so use with caution

enumerator helics_flag_source_only

flag indicating that a federate/interface is a signal generator only

enumerator helics_flag_terminate_on_error

specify that a federate error should terminate the federation

enumerator helics_flag_uninterruptible

flag indicating that a federate can only return requested times

enumerator helics_flag_wait_for_current_time_update

flag indicating a federate should only grant time if all other federates have already passed the requested time

enumerator helics_handle_option_buffer_data

specify that the last data should be buffered and sent on subscriptions after init

enumerator helics_handle_option_connection_optional

specify that a connection is NOT required for an interface and will only be made if available no warning will be issues if not available

enumerator helics_handle_option_connection_required

specify that a connection is required for an interface and will generate an error if not available

enumerator helics_handle_option_ignore_interrupts

specify that an interface does not participate in determining time interrupts

enumerator helics_handle_option_ignore_unit_mismatch

specify that the mismatching units should be ignored

enumerator helics_handle_option_multiple_connections_allowed

specify that multiple connections are allowed for an interface

enumerator helics_handle_option_only_transmit_on_change

specify that an interface will only transmit on change(only applicable to publications)

enumerator helics_handle_option_only_update_on_change

specify that an interface will only update if the value has actually changed

enumerator helics_handle_option_single_connection_only

specify that only a single connection is allowed for an interface

enumerator helics_handle_option_strict_type_checking

specify that the types should be checked strictly for pub/sub and filters

enumerator helics_iteration_request_force_iteration

force iteration return when able

enumerator helics_iteration_request_iterate_if_needed

only return an iteration if necessary

enumerator helics_iteration_request_no_iteration

no iteration is requested

enumerator helics_iteration_result_error

there was an error

enumerator helics_iteration_result_halted

the federation has halted

enumerator helics_iteration_result_iterating

the federate is iterating at current time

enumerator helics_iteration_result_next_step

the iterations have progressed to the next time

enumerator helics_log_level_connections

summary+ notices about federate and broker connections +messages about network connections

enumerator helics_log_level_data

timing+ data transfer notices

enumerator helics_log_level_error

only print error level indicators

enumerator helics_log_level_interfaces

connections+ interface definitions

enumerator helics_log_level_no_print

don’t print anything except a few catastrophic errors

enumerator helics_log_level_summary

warning errors and summary level information

enumerator helics_log_level_timing

interfaces + timing message

enumerator helics_log_level_trace

all internal messages

enumerator helics_log_level_warning

only print warnings and errors

enumerator helics_ok

the function executed successfully

enumerator helics_property_int_console_log_level

integer property controlling the log level for file logging in a federate see helics_log_levels

enumerator helics_property_int_file_log_level

integer property controlling the log level for file logging in a federate see helics_log_levels

enumerator helics_property_int_log_level

integer property controlling the log level in a federate see helics_log_levels

enumerator helics_property_int_max_iterations

integer property controlling the maximum number of iterations in a federate

enumerator helics_property_time_delta

the property controlling the minimum time delta for a federate

enumerator helics_property_time_input_delay

the property controlling input delay for a federate

enumerator helics_property_time_offset

the property controlling time offset for the period of federate

enumerator helics_property_time_output_delay

the property controlling output delay for a federate

enumerator helics_property_time_period

the property controlling the period for a federate

enumerator helics_property_time_rt_lag

the property controlling real time lag for a federate the max time a federate can lag real time

enumerator helics_property_time_rt_lead

the property controlling real time lead for a federate the max time a federate can be ahead of real time

enumerator helics_property_time_rt_tolerance

the property controlling real time tolerance for a federate sets both rt_lag and rt_lead

enumerator helics_state_error

error state no core communication is possible but values can be retrieved

enumerator helics_state_execution

entered after the enterExectuationState call has returned

enumerator helics_state_finalize

the federate has finished executing normally final values may be retrieved

enumerator helics_state_initialization

entered after the enterInitializingMode call has returned

enumerator helics_state_pending_exec

state pending EnterExecution State

enumerator helics_state_pending_finalize

state that the federate is pending a finalize request

enumerator helics_state_pending_init

indicator that the federate is pending entry to initialization state

enumerator helics_state_pending_iterative_time

state that the federate is pending an iterative time request

enumerator helics_state_pending_time

state that the federate is pending a timeRequest

enumerator helics_state_startup

when created the federate is in startup state

enumerator helics_warning

the function issued a warning of some kind

Functions

1. Broker

2. Core

3. Endpoint

4. FederateInfo

5. Federate

6. Filter

7. Input

8. Message

9. Publication

10. Query

Broker

void helicsBrokerAddDestinationFilterToEndpoint(helics_broker broker, const char *filter, const char *endpoint, helics_error *err)

Link a named filter to a destination endpoint.

Parameters

• broker – The broker to generate the connection from.

• filter – The name of the filter (cannot be NULL).

• endpoint – The name of the endpoint to filter the data going to (cannot be NULL). @forcpponly

• err – [inout] A helics_error object, can be NULL if the errors are to be ignored. @endforcpponly

void helicsBrokerAddSourceFilterToEndpoint(helics_broker broker, const char *filter, const char *endpoint, helics_error *err)

Link a named filter to a source endpoint.

Parameters

• broker – The broker to generate the connection from.

• filter – The name of the filter (cannot be NULL).

• endpoint – The name of the endpoint to filter the data from (cannot be NULL). @forcpponly

• err – [inout] A helics_error object, can be NULL if the errors are to be ignored. @endforcpponly

helics_broker helicsBrokerClone(helics_broker broker, helics_error *err)

Create a new reference to an existing broker.

This will create a new broker object that references the existing broker it must be freed as well.

Parameters

• broker – An existing helics_broker. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

A new reference to the same broker.

void helicsBrokerDataLink(helics_broker broker, const char *source, const char *target, helics_error *err)

Link a named publication and named input using a broker.

Parameters

• broker – The broker to generate the connection from.

• source – The name of the publication (cannot be NULL).

• target – The name of the target to send the publication data (cannot be NULL). @forcpponly

• err – [inout] A helics_error object, can be NULL if the errors are to be ignored. @endforcpponly

void helicsBrokerDestroy(helics_broker broker)

Disconnect and free a broker.

void helicsBrokerDisconnect(helics_broker broker, helics_error *err)

Disconnect a broker.

Parameters

• broker – The broker to disconnect. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsBrokerFree(helics_broker broker)

Release the memory associated with a broker.

const char *helicsBrokerGetAddress(helics_broker broker)

Get the network address associated with a broker.

Parameters

broker – The broker to query.

Returns

A string with the network address of the broker.

const char *helicsBrokerGetIdentifier(helics_broker broker)

Get an identifier for the broker.

Parameters

broker – The broker to query.

Returns

A string containing the identifier for the broker.

helics_bool helicsBrokerIsConnected(helics_broker broker)

Check if a broker is connected.

A connected broker implies it is attached to cores or cores could reach out to communicate.

Returns

helics_false if not connected.

helics_bool helicsBrokerIsValid(helics_broker broker)

Check if a broker object is a valid object.

Parameters

broker – The helics_broker object to test.

void helicsBrokerMakeConnections(helics_broker broker, const char *file, helics_error *err)

Load a file containing connection information.

Parameters

• broker – The broker to generate the connections from.

• file – A JSON or TOML file containing connection information. @forcpponly

• err – [inout] A helics_error object, can be NULL if the errors are to be ignored. @endforcpponly

void helicsBrokerSetGlobal(helics_broker broker, const char *valueName, const char *value, helics_error *err)

Set a federation global value.

This overwrites any previous value for this name.

Parameters

• broker – The broker to set the global through.

• valueName – The name of the global to set.

• value – The value of the global. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsBrokerSetLogFile(helics_broker broker, const char *logFileName, helics_error *err)

Set the log file on a broker.

Parameters

• broker – The broker to set the log file for.

• logFileName – The name of the file to log to. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

helics_bool helicsBrokerWaitForDisconnect(helics_broker broker, int msToWait, helics_error *err)

Wait for the broker to disconnect.

Parameters

• broker – The broker to wait for.

• msToWait – The time out in millisecond (<0 for infinite timeout). @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

helics_true if the disconnect was successful, helics_false if there was a timeout.

void helicsBrokerSetLoggingCallback(helics_broker broker, void (*logger)(int loglevel, const char *identifier, const char *message, void *userData), void *userdata, helics_error *err)

Set the logging callback to a broker.

Add a logging callback function to a broker. The logging callback will be called when a message flows into a broker from the core or from a broker.

Parameters

• broker – The broker object in which to set the callback.

• logger – A callback with signature void(int, const char *, const char *, void *); the function arguments are loglevel, an identifier, a message string, and a pointer to user data.

• userdata – A pointer to user data that is passed to the function when executing. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Core

void helicsCoreAddDestinationFilterToEndpoint(helics_core core, const char *filter, const char *endpoint, helics_error *err)

Link a named filter to a destination endpoint.

Parameters

• core – The core to generate the connection from.

• filter – The name of the filter (cannot be NULL).

• endpoint – The name of the endpoint to filter the data going to (cannot be NULL). @forcpponly

• err – [inout] A helics_error object, can be NULL if the errors are to be ignored. @endforcpponly

void helicsCoreAddSourceFilterToEndpoint(helics_core core, const char *filter, const char *endpoint, helics_error *err)

Link a named filter to a source endpoint.

Parameters

• core – The core to generate the connection from.

• filter – The name of the filter (cannot be NULL).

• endpoint – The name of the endpoint to filter the data from (cannot be NULL). @forcpponly

• err – [inout] A helics_error object, can be NULL if the errors are to be ignored. @endforcpponly

helics_core helicsCoreClone(helics_core core, helics_error *err)

Create a new reference to an existing core.

This will create a new broker object that references the existing broker. The new broker object must be freed as well.

Parameters

• core – An existing helics_core. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

A new reference to the same broker.

helics_bool helicsCoreConnect(helics_core core, helics_error *err)

Connect a core to the federate based on current configuration.

Parameters

• core – The core to connect. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

helics_false if not connected, helics_true if it is connected.

void helicsCoreDataLink(helics_core core, const char *source, const char *target, helics_error *err)

Link a named publication and named input using a core.

Parameters

• core – The core to generate the connection from.

• source – The name of the publication (cannot be NULL).

• target – The name of the target to send the publication data (cannot be NULL). @forcpponly

• err – [inout] A helics_error object, can be NULL if the errors are to be ignored. @endforcpponly

void helicsCoreDestroy(helics_core core)

Disconnect and free a core.

void helicsCoreDisconnect(helics_core core, helics_error *err)

Disconnect a core from the federation.

Parameters

• core – The core to query. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsCoreFree(helics_core core)

Release the memory associated with a core.

const char *helicsCoreGetAddress(helics_core core)

Get the network address associated with a core.

Parameters

core – The core to query.

Returns

A string with the network address of the broker.

const char *helicsCoreGetIdentifier(helics_core core)

Get an identifier for the core.

Parameters

core – The core to query.

Returns

A string with the identifier of the core.

helics_bool helicsCoreIsConnected(helics_core core)

Check if a core is connected.

A connected core implies it is attached to federates or federates could be attached to it

Returns

helics_false if not connected, helics_true if it is connected.

helics_bool helicsCoreIsValid(helics_core core)

Check if a core object is a valid object.

Parameters

core – The helics_core object to test.

void helicsCoreMakeConnections(helics_core core, const char *file, helics_error *err)

Load a file containing connection information.

Parameters

• core – The core to generate the connections from.

• file – A JSON or TOML file containing connection information. @forcpponly

• err – [inout] A helics_error object, can be NULL if the errors are to be ignored. @endforcpponly

helics_filter helicsCoreRegisterCloningFilter(helics_core core, const char *name, helics_error *err)

Create a cloning Filter on the specified core.

Cloning filters copy a message and send it to multiple locations, source and destination can be added through other functions.

Parameters

• core – The core to register through.

• name – The name of the filter (can be NULL). @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

A helics_filter object.

helics_filter helicsCoreRegisterFilter(helics_core core, helics_filter_type type, const char *name, helics_error *err)

Create a source Filter on the specified core.

Filters can be created through a federate or a core, linking through a federate allows a few extra features of name matching to function on the federate interface but otherwise equivalent behavior.

Parameters

• core – The core to register through.

• type – The type of filter to create /ref helics_filter_type.

• name – The name of the filter (can be NULL). @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

A helics_filter object.

void helicsCoreSetGlobal(helics_core core, const char *valueName, const char *value, helics_error *err)

Set a global value in a core.

This overwrites any previous value for this name.

Parameters

• core – The core to set the global through.

• valueName – The name of the global to set.

• value – The value of the global. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsCoreSetLogFile(helics_core core, const char *logFileName, helics_error *err)

Set the log file on a core.

Parameters

• core – The core to set the log file for.

• logFileName – The name of the file to log to. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsCoreSetReadyToInit(helics_core core, helics_error *err)

Set the core to ready for init.

This function is used for cores that have filters but no federates so there needs to be a direct signal to the core to trigger the federation initialization.

Parameters

• core – The core object to enable init values for. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

helics_bool helicsCoreWaitForDisconnect(helics_core core, int msToWait, helics_error *err)

Wait for the core to disconnect.

Parameters

• core – The core to wait for.

• msToWait – The time out in millisecond (<0 for infinite timeout). @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

helics_true if the disconnect was successful, helics_false if there was a timeout.

void helicsCoreSetLoggingCallback(helics_core core, void (*logger)(int loglevel, const char *identifier, const char *message, void *userData), void *userdata, helics_error *err)

Set the logging callback for a core.

Add a logging callback function to a core. The logging callback will be called when a message flows into a core from the core or from a broker.

Parameters

• core – The core object in which to set the callback.

• logger – A callback with signature void(int, const char *, const char *, void *); The function arguments are loglevel, an identifier, a message string, and a pointer to user data.

• userdata – A pointer to user data that is passed to the function when executing. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Endpoint

Warning

doxygenfunction: Unable to resolve function “helicsEndpointClearMessages” with arguments “None”. Candidate function could not be parsed. Parsing error is Error when parsing function declaration. If the function has no return type: Error in declarator or parameters-and-qualifiers Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 25] HELICS_DEPRECATED_EXPORT void helicsEndpointClearMessages (helics_endpoint endpoint) ————————-^ If the function has a return type: Error in declarator or parameters-and-qualifiers If pointer to member declarator: Invalid C++ declaration: Expected identifier in nested name, got keyword: void [error at 29] HELICS_DEPRECATED_EXPORT void helicsEndpointClearMessages (helics_endpoint endpoint) —————————–^ If declarator-id: Invalid C++ declaration: Expected identifier in nested name, got keyword: void [error at 29] HELICS_DEPRECATED_EXPORT void helicsEndpointClearMessages (helics_endpoint endpoint) —————————–^

helics_message_object helicsEndpointCreateMessageObject(helics_endpoint endpoint, helics_error *err)

Create a new empty message object.

The message is empty and isValid will return false since there is no data associated with the message yet.

Parameters

• endpoint – The endpoint object to associate the message with. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

Returns

A new helics_message_object.

const char *helicsEndpointGetDefaultDestination(helics_endpoint endpoint)

Get the default destination for an endpoint.

Parameters

endpoint – The endpoint to set the destination for.

Returns

A string with the default destination.

const char *helicsEndpointGetInfo(helics_endpoint end)

Get the data in the info field of a filter.

Parameters

end – The filter to query.

Returns

A string with the info field string.

Warning

doxygenfunction: Unable to resolve function “helicsEndpointGetMessage” with arguments “None”. Candidate function could not be parsed. Parsing error is Error when parsing function declaration. If the function has no return type: Error in declarator or parameters-and-qualifiers Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 25] HELICS_DEPRECATED_EXPORT helics_message helicsEndpointGetMessage (helics_endpoint endpoint) ————————-^ If the function has a return type: Error in declarator or parameters-and-qualifiers If pointer to member declarator: Invalid C++ declaration: Expected ‘::’ in pointer to member (function). [error at 40] HELICS_DEPRECATED_EXPORT helics_message helicsEndpointGetMessage (helics_endpoint endpoint) —————————————-^ If declarator-id: Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 40] HELICS_DEPRECATED_EXPORT helics_message helicsEndpointGetMessage (helics_endpoint endpoint) —————————————-^

helics_message_object helicsEndpointGetMessageObject(helics_endpoint endpoint)

Receive a packet from a particular endpoint.

Parameters

endpoint – [in] The identifier for the endpoint.

Returns

A message object.

const char *helicsEndpointGetName(helics_endpoint endpoint)

Get the name of an endpoint.

Parameters

endpoint – The endpoint object in question.

Returns

The name of the endpoint.

int helicsEndpointGetOption(helics_endpoint endpoint, int option)

Set a handle option on an endpoint.

Parameters

• endpoint – The endpoint to modify.

• option – Integer code for the option to set /ref helics_handle_options.

Returns

the value of the option, for boolean options will be 0 or 1

const char *helicsEndpointGetType(helics_endpoint endpoint)

Get the type specified for an endpoint.

Parameters

endpoint – The endpoint object in question.

Returns

The defined type of the endpoint.

helics_bool helicsEndpointHasMessage(helics_endpoint endpoint)

Check if a given endpoint has any unread messages.

Parameters

endpoint – The endpoint to check.

Returns

helics_true if the endpoint has a message, helics_false otherwise.

helics_bool helicsEndpointIsValid(helics_endpoint endpoint)

Check if an endpoint is valid.

Parameters

endpoint – The endpoint object to check.

Returns

helics_true if the Endpoint object represents a valid endpoint.

Warning

doxygenfunction: Unable to resolve function “helicsEndpointPendingMessages” with arguments “None”. Candidate function could not be parsed. Parsing error is Error when parsing function declaration. If the function has no return type: Error in declarator or parameters-and-qualifiers Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 25] HELICS_DEPRECATED_EXPORT int helicsEndpointPendingMessages (helics_endpoint endpoint) ————————-^ If the function has a return type: Error in declarator or parameters-and-qualifiers If pointer to member declarator: Invalid C++ declaration: Expected identifier in nested name, got keyword: int [error at 28] HELICS_DEPRECATED_EXPORT int helicsEndpointPendingMessages (helics_endpoint endpoint) —————————-^ If declarator-id: Invalid C++ declaration: Expected identifier in nested name, got keyword: int [error at 28] HELICS_DEPRECATED_EXPORT int helicsEndpointPendingMessages (helics_endpoint endpoint) —————————-^

void helicsEndpointSendEventRaw(helics_endpoint endpoint, const char *dst, const void *data, int inputDataLength, helics_time time, helics_error *err)

Send a message at a specific time to the specified destination.

Parameters

• endpoint – The endpoint to send the data from.

• dst – The target destination. @forcpponly nullptr to use the default destination. @endforcpponly @beginpythononly “” to use the default destination. @endpythononly

• data – The data to send. @forcpponly

• inputDataLength – The length of the data to send. @endforcpponly

• time – The time the message should be sent. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Warning

doxygenfunction: Unable to resolve function “helicsEndpointSendMessage” with arguments “None”. Candidate function could not be parsed. Parsing error is Error when parsing function declaration. If the function has no return type: Error in declarator or parameters-and-qualifiers Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 25] HELICS_DEPRECATED_EXPORT void helicsEndpointSendMessage (helics_endpoint endpoint, helics_message *message, helics_error *err) ————————-^ If the function has a return type: Error in declarator or parameters-and-qualifiers If pointer to member declarator: Invalid C++ declaration: Expected identifier in nested name, got keyword: void [error at 29] HELICS_DEPRECATED_EXPORT void helicsEndpointSendMessage (helics_endpoint endpoint, helics_message *message, helics_error *err) —————————–^ If declarator-id: Invalid C++ declaration: Expected identifier in nested name, got keyword: void [error at 29] HELICS_DEPRECATED_EXPORT void helicsEndpointSendMessage (helics_endpoint endpoint, helics_message *message, helics_error *err) —————————–^

void helicsEndpointSendMessageObject(helics_endpoint endpoint, helics_message_object message, helics_error *err)

Send a message object from a specific endpoint.

Parameters

• endpoint – The endpoint to send the data from.

• message – The actual message to send which will be copied. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsEndpointSendMessageObjectZeroCopy(helics_endpoint endpoint, helics_message_object message, helics_error *err)

Send a message object from a specific endpoint, the message will not be copied and the message object will no longer be valid after the call.

Parameters

• endpoint – The endpoint to send the data from.

• message – The actual message to send which will be copied. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsEndpointSendMessageRaw(helics_endpoint endpoint, const char *dst, const void *data, int inputDataLength, helics_error *err)

Send a message to the specified destination.

Parameters

• endpoint – The endpoint to send the data from.

• dst – The target destination. @forcpponly nullptr to use the default destination. @endforcpponly @beginpythononly “” to use the default destination. @endpythononly

• data – The data to send. @forcpponly

• inputDataLength – The length of the data to send.

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsEndpointSetDefaultDestination(helics_endpoint endpoint, const char *dst, helics_error *err)

Set the default destination for an endpoint if no other endpoint is given.

Parameters

• endpoint – The endpoint to set the destination for.

• dst – A string naming the desired default endpoint. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsEndpointSetInfo(helics_endpoint endpoint, const char *info, helics_error *err)

Set the data in the info field for a filter.

Parameters

• endpoint – The endpoint to query.

• info – The string to set. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsEndpointSetOption(helics_endpoint endpoint, int option, int value, helics_error *err)

Set a handle option on an endpoint.

Parameters

• endpoint – The endpoint to modify.

• option – Integer code for the option to set /ref helics_handle_options.

• value – The value to set the option to. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsEndpointSubscribe(helics_endpoint endpoint, const char *key, helics_error *err)

Subscribe an endpoint to a publication.

Parameters

• endpoint – The endpoint to use.

• key – The name of the publication. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

FederateInfo

helics_federate_info helicsFederateInfoClone(helics_federate_info fi, helics_error *err)

Create a federate info object from an existing one and clone the information.

Parameters

• fi – A federateInfo object to duplicate. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

A helics_federate_info object which is a reference to the created object.

void helicsFederateInfoFree(helics_federate_info fi)

Delete the memory associated with a federate info object.

void helicsFederateInfoLoadFromArgs(helics_federate_info fi, int argc, const char *const *argv, helics_error *err)

Load federate info from command line arguments.

Parameters

• fi – A federateInfo object.

• argc – The number of command line arguments.

• argv – An array of strings from the command line. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateInfoSetBroker(helics_federate_info fi, const char *broker, helics_error *err)

Set the name or connection information for a broker.

This is only used if the core is automatically created, the broker information will be transferred to the core for connection.

Parameters

• fi – The federate info object to alter.

• broker – A string which defines the connection information for a broker either a name or an address. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateInfoSetBrokerInitString(helics_federate_info fi, const char *brokerInit, helics_error *err)

Set the initialization string that a core will pass to a generated broker usually in the form of command line arguments.

Parameters

• fi – The federate info object to alter.

• brokerInit – A string with command line arguments for a generated broker. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateInfoSetBrokerKey(helics_federate_info fi, const char *brokerkey, helics_error *err)

Set the key for a broker connection.

This is only used if the core is automatically created, the broker information will be transferred to the core for connection.

Parameters

• fi – The federate info object to alter.

• brokerkey – A string containing a key for the broker to connect. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateInfoSetBrokerPort(helics_federate_info fi, int brokerPort, helics_error *err)

Set the port to use for the broker.

This is only used if the core is automatically created, the broker information will be transferred to the core for connection. This will only be useful for network broker connections.

Parameters

• fi – The federate info object to alter.

• brokerPort – The integer port number to use for connection with a broker. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateInfoSetCoreInitString(helics_federate_info fi, const char *coreInit, helics_error *err)

Set the initialization string for the core usually in the form of command line arguments.

Parameters

• fi – The federate info object to alter.

• coreInit – A string containing command line arguments to be passed to the core. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateInfoSetCoreName(helics_federate_info fi, const char *corename, helics_error *err)

Set the name of the core to link to for a federate.

Parameters

• fi – The federate info object to alter.

• corename – The identifier for a core to link to. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateInfoSetCoreType(helics_federate_info fi, int coretype, helics_error *err)

Set the core type by integer code.

Valid values available by definitions in api-data.h.

Parameters

• fi – The federate info object to alter.

• coretype – An numerical code for a core type see /ref helics_core_type. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateInfoSetCoreTypeFromString(helics_federate_info fi, const char *coretype, helics_error *err)

Set the core type from a string.

Parameters

• fi – The federate info object to alter.

• coretype – A string naming a core type. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateInfoSetFlagOption(helics_federate_info fi, int flag, helics_bool value, helics_error *err)

Set a flag in the info structure.

Valid flags are available /ref helics_federate_flags.

Parameters

• fi – The federate info object to alter.

• flag – A numerical index for a flag.

• value – The desired value of the flag helics_true or helics_false. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateInfoSetIntegerProperty(helics_federate_info fi, int intProperty, int propertyValue, helics_error *err)

Set an integer property for a federate.

Set known properties.

Parameters

• fi – The federateInfo object to alter.

• intProperty – An int identifying the property.

• propertyValue – The value to set the property to. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateInfoSetLocalPort(helics_federate_info fi, const char *localPort, helics_error *err)

Set the local port to use.

This is only used if the core is automatically created, the port information will be transferred to the core for connection.

Parameters

• fi – The federate info object to alter.

• localPort – A string with the port information to use as the local server port can be a number or “auto” or “os_local”. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateInfoSetSeparator(helics_federate_info fi, char separator, helics_error *err)

Set the separator character in the info structure.

The separator character is the separation character for local publications/endpoints in creating their global name. For example if the separator character is ‘/’ then a local endpoint would have a globally reachable name of fedName/localName.

Parameters

• fi – The federate info object to alter.

• separator – The character to use as a separator. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateInfoSetTimeProperty(helics_federate_info fi, int timeProperty, helics_time propertyValue, helics_error *err)

Set the output delay for a federate.

Parameters

• fi – The federate info object to alter.

• timeProperty – An integer representation of the time based property to set see /ref helics_properties.

• propertyValue – The value of the property to set the timeProperty to. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Federate

void helicsFederateAddDependency(helics_federate fed, const char *fedName, helics_error *err)

Add a time dependency for a federate. The federate will depend on the given named federate for time synchronization.

Parameters

• fed – The federate to add the dependency for.

• fedName – The name of the federate to depend on. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsFederateClearMessages(helics_federate fed)

Clear all stored messages from a federate.

This clears messages retrieved through helicsFederateGetMessage or helicsFederateGetMessageObject

Parameters

fed – The federate to clear the message for.

void helicsFederateClearUpdates(helics_federate fed)

Clear all the update flags from a federates inputs.

Parameters

fed – The value federate object for which to clear update flags.

helics_federate helicsFederateClone(helics_federate fed, helics_error *err)

Create a new reference to an existing federate.

This will create a new helics_federate object that references the existing federate. The new object must be freed as well.

Parameters

• fed – An existing helics_federate. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

A new reference to the same federate.

helics_message_object helicsFederateCreateMessageObject(helics_federate fed, helics_error *err)

Create a new empty message object.

The message is empty and isValid will return false since there is no data associated with the message yet.

Parameters

• fed – the federate object to associate the message with @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

Returns

A helics_message_object containing the message data.

void helicsFederateDestroy(helics_federate fed)

Disconnect and free a federate.

void helicsFederateEnterExecutingMode(helics_federate fed, helics_error *err)

Request that the federate enter the Execution mode.

This call is blocking until granted entry by the core object. On return from this call the federate will be at time 0. For an asynchronous alternative call see /ref helicsFederateEnterExecutingModeAsync.

Parameters

• fed – A federate to change modes. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateEnterExecutingModeAsync(helics_federate fed, helics_error *err)

Request that the federate enter the Execution mode.

This call is non-blocking and will return immediately. Call /ref helicsFederateEnterExecutingModeComplete to finish the call sequence.

Parameters

• fed – The federate object to complete the call. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateEnterExecutingModeComplete(helics_federate fed, helics_error *err)

Complete the call to /ref helicsFederateEnterExecutingModeAsync.

Parameters

• fed – The federate object to complete the call. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

helics_iteration_result helicsFederateEnterExecutingModeIterative(helics_federate fed, helics_iteration_request iterate, helics_error *err)

Request an iterative time.

This call allows for finer grain control of the iterative process than /ref helicsFederateRequestTime. It takes a time and iteration request, and returns a time and iteration status.

Parameters

• fed – The federate to make the request of.

• iterate – The requested iteration mode. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

An iteration structure with field containing the time and iteration status.

void helicsFederateEnterExecutingModeIterativeAsync(helics_federate fed, helics_iteration_request iterate, helics_error *err)

Request an iterative entry to the execution mode.

This call allows for finer grain control of the iterative process than /ref helicsFederateRequestTime. It takes a time and iteration request, and returns a time and iteration status

Parameters

• fed – The federate to make the request of.

• iterate – The requested iteration mode. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

helics_iteration_result helicsFederateEnterExecutingModeIterativeComplete(helics_federate fed, helics_error *err)

Complete the asynchronous iterative call into ExecutionMode.

Parameters

• fed – The federate to make the request of. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

An iteration object containing the iteration time and iteration_status.

void helicsFederateEnterInitializingMode(helics_federate fed, helics_error *err)

Enter the initialization state of a federate.

The initialization state allows initial values to be set and received if the iteration is requested on entry to the execution state. This is a blocking call and will block until the core allows it to proceed.

Parameters

• fed – The federate to operate on. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateEnterInitializingModeAsync(helics_federate fed, helics_error *err)

Non blocking alternative to helicsFederateEnterInitializingMode.

The function helicsFederateEnterInitializationModeFinalize must be called to finish the operation.

Parameters

• fed – The federate to operate on. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateEnterInitializingModeComplete(helics_federate fed, helics_error *err)

Finalize the entry to initialize mode that was initiated with /ref heliceEnterInitializingModeAsync.

Parameters

• fed – The federate desiring to complete the initialization step. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateFinalize(helics_federate fed, helics_error *err)

Finalize the federate. This function halts all communication in the federate and disconnects it from the core.

void helicsFederateFinalizeAsync(helics_federate fed, helics_error *err)

Finalize the federate in an async call.

void helicsFederateFinalizeComplete(helics_federate fed, helics_error *err)

Complete the asynchronous finalize call.

void helicsFederateFree(helics_federate fed)

Release the memory associated with a federate.

helics_core helicsFederateGetCoreObject(helics_federate fed, helics_error *err)

Get the core object associated with a federate.

Parameters

• fed – A federate object. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

A core object, nullptr if invalid.

helics_time helicsFederateGetCurrentTime(helics_federate fed, helics_error *err)

Get the current time of the federate.

Parameters

• fed – The federate object to query. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

The current time of the federate.

helics_endpoint helicsFederateGetEndpoint(helics_federate fed, const char *name, helics_error *err)

Get an endpoint object from a name.

Parameters

• fed – The message federate object to use to get the endpoint.

• name – The name of the endpoint. @forcpponly

• err – [inout] The error object to complete if there is an error. @endforcpponly

Returns

A helics_endpoint object. @forcpponly The object will not be valid and err will contain an error code if no endpoint with the specified name exists. @endforcpponly

helics_endpoint helicsFederateGetEndpointByIndex(helics_federate fed, int index, helics_error *err)

Get an endpoint by its index, typically already created via registerInterfaces file or something of that nature.

Parameters

• fed – The federate object in which to create a publication.

• index – The index of the publication to get. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

A helics_endpoint. @forcpponly It will be NULL if given an invalid index. @endforcpponly

int helicsFederateGetEndpointCount(helics_federate fed)

Get the number of endpoints in a federate.

Parameters

fed – The message federate to query.

Returns

(-1) if fed was not a valid federate, otherwise returns the number of endpoints.

helics_filter helicsFederateGetFilter(helics_federate fed, const char *name, helics_error *err)

Get a filter by its name, typically already created via registerInterfaces file or something of that nature.

Parameters

• fed – The federate object to use to get the filter.

• name – The name of the filter. @forcpponly

• err – [inout] The error object to complete if there is an error. @endforcpponly

Returns

A helics_filter object, the object will not be valid and err will contain an error code if no filter with the specified name exists.

helics_filter helicsFederateGetFilterByIndex(helics_federate fed, int index, helics_error *err)

Get a filter by its index, typically already created via registerInterfaces file or something of that nature.

Parameters

• fed – The federate object in which to create a publication.

• index – The index of the publication to get. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

A helics_filter, which will be NULL if an invalid index is given.

int helicsFederateGetFilterCount(helics_federate fed)

Get the number of filters registered through a federate.

Parameters

fed – The federate object to use to get the filter.

Returns

A count of the number of filters registered through a federate.

helics_bool helicsFederateGetFlagOption(helics_federate fed, int flag, helics_error *err)

Get a flag value for a federate.

Parameters

• fed – The federate to get the flag for.

• flag – The flag to query. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

The value of the flag.

helics_input helicsFederateGetInput(helics_federate fed, const char *key, helics_error *err)

Get an input object from a key.

Parameters

• fed – The value federate object to use to get the publication.

• key – The name of the input. @forcpponly

• err – [inout] The error object to complete if there is an error. @endforcpponly

Returns

A helics_input object, the object will not be valid and err will contain an error code if no input with the specified key exists.

helics_input helicsFederateGetInputByIndex(helics_federate fed, int index, helics_error *err)

Get an input by its index, typically already created via registerInterfaces file or something of that nature.

Parameters

• fed – The federate object in which to create a publication.

• index – The index of the publication to get. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

A helics_input, which will be NULL if an invalid index.

int helicsFederateGetInputCount(helics_federate fed)

Get the number of subscriptions in a federate.

Returns

(-1) if fed was not a valid federate otherwise returns the number of subscriptions.

int helicsFederateGetIntegerProperty(helics_federate fed, int intProperty, helics_error *err)

Get the current value of an integer property (such as a logging level).

Parameters

• fed – The federate to get the flag for.

• intProperty – A code for the property to set /ref helics_handle_options. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

The value of the property.

Warning

doxygenfunction: Unable to resolve function “helicsFederateGetMessage” with arguments “None”. Candidate function could not be parsed. Parsing error is Error when parsing function declaration. If the function has no return type: Error in declarator or parameters-and-qualifiers Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 25] HELICS_DEPRECATED_EXPORT helics_message helicsFederateGetMessage (helics_federate fed) ————————-^ If the function has a return type: Error in declarator or parameters-and-qualifiers If pointer to member declarator: Invalid C++ declaration: Expected ‘::’ in pointer to member (function). [error at 40] HELICS_DEPRECATED_EXPORT helics_message helicsFederateGetMessage (helics_federate fed) —————————————-^ If declarator-id: Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 40] HELICS_DEPRECATED_EXPORT helics_message helicsFederateGetMessage (helics_federate fed) —————————————-^

helics_message_object helicsFederateGetMessageObject(helics_federate fed)

Receive a communication message for any endpoint in the federate.

The return order will be in order of endpoint creation. So all messages that are available for the first endpoint, then all for the second, and so on. Within a single endpoint, the messages are ordered by time, then source_id, then order of arrival.

Returns

A helics_message_object which references the data in the message.

const char *helicsFederateGetName(helics_federate fed)

Get the name of the federate.

Parameters

fed – The federate object to query.

Returns

A pointer to a string with the name.

helics_publication helicsFederateGetPublication(helics_federate fed, const char *key, helics_error *err)

Get a publication object from a key.

Parameters

• fed – The value federate object to use to get the publication.

• key – The name of the publication. @forcpponly

• err – [inout] The error object to complete if there is an error. @endforcpponly

Returns

A helics_publication object, the object will not be valid and err will contain an error code if no publication with the specified key exists.

helics_publication helicsFederateGetPublicationByIndex(helics_federate fed, int index, helics_error *err)

Get a publication by its index, typically already created via registerInterfaces file or something of that nature.

Parameters

• fed – The federate object in which to create a publication.

• index – The index of the publication to get. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

A helics_publication.

int helicsFederateGetPublicationCount(helics_federate fed)

Get the number of publications in a federate.

Returns

(-1) if fed was not a valid federate otherwise returns the number of publications.

helics_federate_state helicsFederateGetState(helics_federate fed, helics_error *err)

Get the current state of a federate.

Parameters

• fed – The federate to query. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

State the resulting state if void return helics_ok.

helics_input helicsFederateGetSubscription(helics_federate fed, const char *key, helics_error *err)

Get an input object from a subscription target.

Parameters

• fed – The value federate object to use to get the publication.

• key – The name of the publication that a subscription is targeting. @forcpponly

• err – [inout] The error object to complete if there is an error. @endforcpponly

Returns

A helics_input object, the object will not be valid and err will contain an error code if no input with the specified key exists.

helics_time helicsFederateGetTimeProperty(helics_federate fed, int timeProperty, helics_error *err)

Get the current value of a time based property in a federate.

Parameters

• fed – The federate query.

• timeProperty – The property to query. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateGlobalError(helics_federate fed, int errorCode, const char *errorString)

Generate a global error from a federate.

A global error halts the co-simulation completely.

Parameters

• fed – The federate to create an error in.

• errorCode – The integer code for the error.

• errorString – A string describing the error.

helics_bool helicsFederateHasMessage(helics_federate fed)

Check if the federate has any outstanding messages.

Parameters

fed – The federate to check.

Returns

helics_true if the federate has a message waiting, helics_false otherwise.

helics_bool helicsFederateIsAsyncOperationCompleted(helics_federate fed, helics_error *err)

Check if the current Asynchronous operation has completed.

Parameters

• fed – The federate to operate on. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

helics_false if not completed, helics_true if completed.

helics_bool helicsFederateIsValid(helics_federate fed)

Check if a federate_object is valid.

Returns

helics_true if the federate is a valid active federate, helics_false otherwise

void helicsFederateLocalError(helics_federate fed, int errorCode, const char *errorString)

Generate a local error in a federate.

This will propagate through the co-simulation but not necessarily halt the co-simulation, it has a similar effect to finalize but does allow some interaction with a core for a brief time.

Parameters

• fed – The federate to create an error in.

• errorCode – The integer code for the error.

• errorString – A string describing the error.

void helicsFederateLogDebugMessage(helics_federate fed, const char *logmessage, helics_error *err)

Log a debug message through a federate.

Parameters

• fed – The federate to log the debug message through.

• logmessage – The message to put in the log. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsFederateLogErrorMessage(helics_federate fed, const char *logmessage, helics_error *err)

Log an error message through a federate.

Parameters

• fed – The federate to log the error message through.

• logmessage – The message to put in the log. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsFederateLogInfoMessage(helics_federate fed, const char *logmessage, helics_error *err)

Log an info message through a federate.

Parameters

• fed – The federate to log the info message through.

• logmessage – The message to put in the log. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsFederateLogLevelMessage(helics_federate fed, int loglevel, const char *logmessage, helics_error *err)

Log a message through a federate.

Parameters

• fed – The federate to log the message through.

• loglevel – The level of the message to log see /ref helics_log_levels.

• logmessage – The message to put in the log. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsFederateLogWarningMessage(helics_federate fed, const char *logmessage, helics_error *err)

Log a warning message through a federate.

Parameters

• fed – The federate to log the warning message through.

• logmessage – The message to put in the log. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Warning

doxygenfunction: Unable to resolve function “helicsFederatePendingMessages” with arguments “None”. Candidate function could not be parsed. Parsing error is Error when parsing function declaration. If the function has no return type: Error in declarator or parameters-and-qualifiers Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 25] HELICS_DEPRECATED_EXPORT int helicsFederatePendingMessages (helics_federate fed) ————————-^ If the function has a return type: Error in declarator or parameters-and-qualifiers If pointer to member declarator: Invalid C++ declaration: Expected identifier in nested name, got keyword: int [error at 28] HELICS_DEPRECATED_EXPORT int helicsFederatePendingMessages (helics_federate fed) —————————-^ If declarator-id: Invalid C++ declaration: Expected identifier in nested name, got keyword: int [error at 28] HELICS_DEPRECATED_EXPORT int helicsFederatePendingMessages (helics_federate fed) —————————-^

void helicsFederatePublishJSON(helics_federate fed, const char *json, helics_error *err)

Publish data contained in a JSON file or string.

Parameters

• fed – The value federate object through which to publish the data.

• json – The publication file name or literal JSON data string. @forcpponly

• err – [inout] The error object to complete if there is an error. @endforcpponly

helics_filter helicsFederateRegisterCloningFilter(helics_federate fed, const char *name, helics_error *err)

Create a cloning Filter on the specified federate.

Cloning filters copy a message and send it to multiple locations, source and destination can be added through other functions.

Parameters

• fed – The federate to register through.

• name – The name of the filter (can be NULL). @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

A helics_filter object.

helics_endpoint helicsFederateRegisterEndpoint(helics_federate fed, const char *name, const char *type, helics_error *err)

Create an endpoint.

The endpoint becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for endpoints.

Parameters

• fed – The federate object in which to create an endpoint must have been created with helicsCreateMessageFederate or helicsCreateCombinationFederate.

• name – The identifier for the endpoint. This will be prepended with the federate name for the global identifier.

• type – A string describing the expected type of the publication (may be NULL). @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

An object containing the endpoint. @forcpponly nullptr on failure. @endforcpponly

helics_filter helicsFederateRegisterFilter(helics_federate fed, helics_filter_type type, const char *name, helics_error *err)

Create a source Filter on the specified federate.

Filters can be created through a federate or a core, linking through a federate allows a few extra features of name matching to function on the federate interface but otherwise equivalent behavior

Parameters

• fed – The federate to register through.

• type – The type of filter to create /ref helics_filter_type.

• name – The name of the filter (can be NULL). @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

A helics_filter object.

void helicsFederateRegisterFromPublicationJSON(helics_federate fed, const char *json, helics_error *err)

Register the publications via JSON publication string.

This would be the same JSON that would be used to publish data.

Parameters

• fed – The value federate object to use to register the publications.

• json – The JSON publication string. @forcpponly

• err – [inout] The error object to complete if there is an error. @endforcpponly

helics_filter helicsFederateRegisterGlobalCloningFilter(helics_federate fed, const char *name, helics_error *err)

Create a global cloning Filter on the specified federate.

Cloning filters copy a message and send it to multiple locations, source and destination can be added through other functions.

Parameters

• fed – The federate to register through.

• name – The name of the filter (can be NULL). @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

A helics_filter object.

helics_endpoint helicsFederateRegisterGlobalEndpoint(helics_federate fed, const char *name, const char *type, helics_error *err)

Create an endpoint.

The endpoint becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for endpoints.

Parameters

• fed – The federate object in which to create an endpoint must have been created with helicsCreateMessageFederate or helicsCreateCombinationFederate.

• name – The identifier for the endpoint, the given name is the global identifier.

• type – A string describing the expected type of the publication (may be NULL). @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

An object containing the endpoint. @forcpponly nullptr on failure. @endforcpponly

helics_filter helicsFederateRegisterGlobalFilter(helics_federate fed, helics_filter_type type, const char *name, helics_error *err)

Create a global source filter through a federate.

Filters can be created through a federate or a core, linking through a federate allows a few extra features of name matching to function on the federate interface but otherwise equivalent behavior.

Parameters

• fed – The federate to register through.

• type – The type of filter to create /ref helics_filter_type.

• name – The name of the filter (can be NULL). @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

A helics_filter object.

helics_publication helicsFederateRegisterGlobalInput(helics_federate fed, const char *key, helics_data_type type, const char *units, helics_error *err)

Register a global named input.

The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.

Parameters

• fed – The federate object in which to create a publication.

• key – The identifier for the publication.

• type – A code identifying the type of the input see /ref helics_data_type for available options.

• units – A string listing the units of the subscription maybe NULL. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

An object containing the publication.

helics_publication helicsFederateRegisterGlobalPublication(helics_federate fed, const char *key, helics_data_type type, const char *units, helics_error *err)

Register a global named publication with an arbitrary type.

The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.

Parameters

• fed – The federate object in which to create a publication.

• key – The identifier for the publication.

• type – A code identifying the type of the input see /ref helics_data_type for available options.

• units – A string listing the units of the subscription (may be NULL). @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

An object containing the publication.

helics_publication helicsFederateRegisterGlobalTypeInput(helics_federate fed, const char *key, const char *type, const char *units, helics_error *err)

Register a global publication with an arbitrary type.

The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.

Parameters

• fed – The federate object in which to create a publication.

• key – The identifier for the publication.

• type – A string defining the type of the input.

• units – A string listing the units of the subscription maybe NULL. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

An object containing the publication.

helics_publication helicsFederateRegisterGlobalTypePublication(helics_federate fed, const char *key, const char *type, const char *units, helics_error *err)

Register a global publication with a defined type.

The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.

Parameters

• fed – The federate object in which to create a publication.

• key – The identifier for the publication.

• type – A string describing the expected type of the publication.

• units – A string listing the units of the subscription (may be NULL). @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

An object containing the publication.

helics_input helicsFederateRegisterInput(helics_federate fed, const char *key, helics_data_type type, const char *units, helics_error *err)

Register a named input.

The input becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions, inputs, and publications.

Parameters

• fed – The federate object in which to create an input.

• key – The identifier for the publication the global input key will be prepended with the federate name.

• type – A code identifying the type of the input see /ref helics_data_type for available options.

• units – A string listing the units of the input (may be NULL). @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

An object containing the input.

void helicsFederateRegisterInterfaces(helics_federate fed, const char *file, helics_error *err)

Load interfaces from a file.

Parameters

• fed – The federate to which to load interfaces.

• file – The name of a file to load the interfaces from either JSON, or TOML. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

helics_publication helicsFederateRegisterPublication(helics_federate fed, const char *key, helics_data_type type, const char *units, helics_error *err)

Register a publication with a known type.

The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.

Parameters

• fed – The federate object in which to create a publication.

• key – The identifier for the publication the global publication key will be prepended with the federate name.

• type – A code identifying the type of the input see /ref helics_data_type for available options.

• units – A string listing the units of the subscription (may be NULL). @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

An object containing the publication.

helics_input helicsFederateRegisterSubscription(helics_federate fed, const char *key, const char *units, helics_error *err)

sub/pub registration Create a subscription.

The subscription becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.

Parameters

• fed – The federate object in which to create a subscription, must have been created with /ref helicsCreateValueFederate or /ref helicsCreateCombinationFederate.

• key – The identifier matching a publication to get a subscription for.

• units – A string listing the units of the subscription (may be NULL). @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

An object containing the subscription.

helics_input helicsFederateRegisterTypeInput(helics_federate fed, const char *key, const char *type, const char *units, helics_error *err)

Register an input with a defined type.

The input becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions, inputs, and publications.

Parameters

• fed – The federate object in which to create an input.

• key – The identifier for the input.

• type – A string describing the expected type of the input.

• units – A string listing the units of the input maybe NULL. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

An object containing the publication.

helics_publication helicsFederateRegisterTypePublication(helics_federate fed, const char *key, const char *type, const char *units, helics_error *err)

Register a publication with a defined type.

The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.

Parameters

• fed – The federate object in which to create a publication.

• key – The identifier for the publication.

• type – A string labeling the type of the publication.

• units – A string listing the units of the subscription (may be NULL). @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

An object containing the publication.

helics_time helicsFederateRequestNextStep(helics_federate fed, helics_error *err)

Request the next time step for federate execution.

Feds should have setup the period or minDelta for this to work well but it will request the next time step which is the current time plus the minimum time step.

Parameters

• fed – The federate to make the request of. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

The time granted to the federate, will return helics_time_maxtime if the simulation has terminated or is invalid

helics_time helicsFederateRequestTime(helics_federate fed, helics_time requestTime, helics_error *err)

Request the next time for federate execution.

Parameters

• fed – The federate to make the request of.

• requestTime – The next requested time. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

The time granted to the federate, will return helics_time_maxtime if the simulation has terminated or is invalid.

helics_time helicsFederateRequestTimeAdvance(helics_federate fed, helics_time timeDelta, helics_error *err)

Request the next time for federate execution.

Parameters

• fed – The federate to make the request of.

• timeDelta – The requested amount of time to advance. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

The time granted to the federate, will return helics_time_maxtime if the simulation has terminated or is invalid

void helicsFederateRequestTimeAsync(helics_federate fed, helics_time requestTime, helics_error *err)

Request the next time for federate execution in an asynchronous call.

Call /ref helicsFederateRequestTimeComplete to finish the call.

Parameters

• fed – The federate to make the request of.

• requestTime – The next requested time. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

helics_time helicsFederateRequestTimeComplete(helics_federate fed, helics_error *err)

Complete an asynchronous requestTime call.

Parameters

• fed – The federate to make the request of. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

The time granted to the federate, will return helics_time_maxtime if the simulation has terminated.

helics_time helicsFederateRequestTimeIterative(helics_federate fed, helics_time requestTime, helics_iteration_request iterate, helics_iteration_result *outIteration, helics_error *err)

Request an iterative time.

This call allows for finer grain control of the iterative process than /ref helicsFederateRequestTime. It takes a time and and iteration request, and returns a time and iteration status.

Parameters

• fed – The federate to make the request of.

• requestTime – The next desired time.

• iterate – The requested iteration mode. @forcpponly

• outIteration – [out] The iteration specification of the result. @endforcpponly @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

The granted time, will return helics_time_maxtime if the simulation has terminated along with the appropriate iteration result. @beginPythonOnly This function also returns the iteration specification of the result. @endPythonOnly

void helicsFederateRequestTimeIterativeAsync(helics_federate fed, helics_time requestTime, helics_iteration_request iterate, helics_error *err)

Request an iterative time through an asynchronous call.

This call allows for finer grain control of the iterative process than /ref helicsFederateRequestTime. It takes a time and iteration request, and returns a time and iteration status. Call /ref helicsFederateRequestTimeIterativeComplete to finish the process.

Parameters

• fed – The federate to make the request of.

• requestTime – The next desired time.

• iterate – The requested iteration mode. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

helics_time helicsFederateRequestTimeIterativeComplete(helics_federate fed, helics_iteration_result *outIterate, helics_error *err)

Complete an iterative time request asynchronous call.

Parameters

• fed – The federate to make the request of. @forcpponly

• outIterate – [out] The iteration specification of the result.

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

The granted time, will return helics_time_maxtime if the simulation has terminated. @beginPythonOnly This function also returns the iteration specification of the result. @endPythonOnly

void helicsFederateSetFlagOption(helics_federate fed, int flag, helics_bool flagValue, helics_error *err)

Set a flag for the federate.

Parameters

• fed – The federate to alter a flag for.

• flag – The flag to change.

• flagValue – The new value of the flag. 0 for false, !=0 for true. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateSetGlobal(helics_federate fed, const char *valueName, const char *value, helics_error *err)

Set a federation global value through a federate.

This overwrites any previous value for this name.

Parameters

• fed – The federate to set the global through.

• valueName – The name of the global to set.

• value – The value of the global. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsFederateSetIntegerProperty(helics_federate fed, int intProperty, int propertyVal, helics_error *err)

Set an integer based property of a federate.

Parameters

• fed – The federate to change the property for.

• intProperty – The property to set.

• propertyVal – The value of the property. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateSetLogFile(helics_federate fed, const char *logFile, helics_error *err)

Set the logging file for a federate (actually on the core associated with a federate).

Parameters

• fed – The federate to set the log file for.

• logFile – The name of the log file. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsFederateSetSeparator(helics_federate fed, char separator, helics_error *err)

Set the separator character in a federate.

The separator character is the separation character for local publications/endpoints in creating their global name. For example if the separator character is ‘/’ then a local endpoint would have a globally reachable name of fedName/localName.

Parameters

• fed – The federate info object to alter.

• separator – The character to use as a separator. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsFederateSetTimeProperty(helics_federate fed, int timeProperty, helics_time time, helics_error *err)

Set a time based property for a federate.

Parameters

• fed – The federate object to set the property for.

• timeProperty – A integer code for a time property.

• time – The requested value of the property. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Warning

doxygenfunction: Cannot find function “helicsFederateEnterInitializingModeCompleted” in doxygen xml output for project “helics” from directory: /home/docs/checkouts/readthedocs.org/user_builds/helics/checkouts/helics2/build-doxygen/docs/xml

void helicsFederateSetLoggingCallback(helics_federate fed, void (*logger)(int loglevel, const char *identifier, const char *message, void *userData), void *userdata, helics_error *err)

Set the logging callback for a federate.

Add a logging callback function to a federate. The logging callback will be called when a message flows into a federate from the core or from a federate.

Parameters

• fed – The federate object in which to create a subscription must have been created with helicsCreateValueFederate or helicsCreateCombinationFederate.

• logger – A callback with signature void(int, const char *, const char *, void *); The function arguments are loglevel, an identifier string, a message string, and a pointer to user data.

• userdata – A pointer to user data that is passed to the function when executing. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Filter

void helicsFilterAddDeliveryEndpoint(helics_filter filt, const char *deliveryEndpoint, helics_error *err)

Add a delivery endpoint to a cloning filter.

All cloned messages are sent to the delivery address(es).

Parameters

• filt – The given filter.

• deliveryEndpoint – The name of the endpoint to deliver messages to. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsFilterAddDestinationTarget(helics_filter filt, const char *dst, helics_error *err)

Add a destination target to a filter.

All messages going to a destination are copied to the delivery address(es).

Parameters

• filt – The given filter to add a destination target to.

• dst – The name of the endpoint to add as a destination target. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsFilterAddSourceTarget(helics_filter filt, const char *source, helics_error *err)

Add a source target to a filter.

All messages coming from a source are copied to the delivery address(es).

Parameters

• filt – The given filter.

• source – The name of the endpoint to add as a source target. @forcpponly.

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

const char *helicsFilterGetInfo(helics_filter filt)

Get the data in the info field of a filter.

Parameters

filt – The given filter.

Returns

A string with the info field string.

const char *helicsFilterGetName(helics_filter filt)

Get the name of the filter and store in the given string.

get the name of the filter

Parameters

filt – The given filter.

Returns

A string with the name of the filter.

int helicsFilterGetOption(helics_filter filt, int option)

Get a handle option for the filter.

Parameters

• filt – The given filter to query.

• option – The option to query /ref helics_handle_options.

helics_bool helicsFilterIsValid(helics_filter filt)

Check if a filter is valid.

Parameters

filt – The filter object to check.

Returns

helics_true if the Filter object represents a valid filter.

void helicsFilterRemoveDeliveryEndpoint(helics_filter filt, const char *deliveryEndpoint, helics_error *err)

Remove a delivery destination from a cloning filter.

Parameters

• filt – The given filter (must be a cloning filter).

• deliveryEndpoint – A string with the delivery endpoint to remove. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsFilterRemoveTarget(helics_filter filt, const char *target, helics_error *err)

Remove a destination target from a filter.

Parameters

• filt – The given filter.

• target – The named endpoint to remove as a target. @forcpponly @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsFilterSet(helics_filter filt, const char *prop, double val, helics_error *err)

Set a property on a filter.

Parameters

• filt – The filter to modify.

• prop – A string containing the property to set.

• val – A numerical value for the property. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsFilterSetInfo(helics_filter filt, const char *info, helics_error *err)

Set the data in the info field for a filter.

Parameters

• filt – The given filter.

• info – The string to set. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsFilterSetOption(helics_filter filt, int option, int value, helics_error *err)

Set the data in the info field for a filter.

Parameters

• filt – The given filter.

• option – The option to set /ref helics_handle_options.

• value – The value of the option commonly 0 for false 1 for true. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsFilterSetString(helics_filter filt, const char *prop, const char *val, helics_error *err)

Set a string property on a filter.

Parameters

• filt – The filter to modify.

• prop – A string containing the property to set.

• val – A string containing the new value. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsFilterSetCustomCallback(helics_filter filter, void (*filtCall)(helics_message_object message, void *userData), void *userdata, helics_error *err)

Set a general callback for a custom filter.

Add a custom filter callback for creating a custom filter operation in the C shared library.

Parameters

• filter – The filter object to set the callback for.

• filtCall – A callback with signature helics_message_object(helics_message_object, void *); The function arguments are the message to filter and a pointer to user data. The filter should return a new message.

• userdata – A pointer to user data that is passed to the function when executing. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Input

void helicsInputAddTarget(helics_input ipt, const char *target, helics_error *err)

Add a publication to the list of data that an input subscribes to.

Parameters

• ipt – The named input to modify.

• target – The name of a publication that an input should subscribe to. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsInputClearUpdate(helics_input ipt)

Clear the updated flag from an input.

helics_bool helicsInputGetBoolean(helics_input ipt, helics_error *err)

Get a boolean value from a subscription.

Parameters

• ipt – The input to get the data for. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

A boolean value of current input value.

char helicsInputGetChar(helics_input ipt, helics_error *err)

Get a single character value from an input.

Parameters

• ipt – The input to get the data for. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

The resulting character value. @forcpponly NAK (negative acknowledgment) symbol returned on error @endforcpponly

void helicsInputGetComplex(helics_input ipt, double *real, double *imag, helics_error *err)

Get a pair of double forming a complex number from a subscriptions.

@beginPythonOnly

Parameters

• ipt – The input to get the data for. @forcpponly

• real – [out] Memory location to place the real part of a value.

• imag – [out] Memory location to place the imaginary part of a value.

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. On error the values will not be altered. @endforcpponly

Returns

a pair of floating point values that represent the real and imag values @endPythonOnly

helics_complex helicsInputGetComplexObject(helics_input ipt, helics_error *err)

Get a complex object from an input object.

Parameters

• ipt – The input to get the data for. @forcpponly

• err – [inout] A helics error object, if the object is not empty the function is bypassed otherwise it is filled in if there is an error. @endforcpponly

Returns

A helics_complex structure with the value.

double helicsInputGetDouble(helics_input ipt, helics_error *err)

Get a double value from a subscription.

Parameters

• ipt – The input to get the data for. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

The double value of the input.

const char *helicsInputGetExtractionUnits(helics_input ipt)

Get the units of an input.

The same as helicsInputGetUnits.

Parameters

ipt – The input to query.

Returns

A void enumeration, helics_ok if everything worked.

const char *helicsInputGetInfo(helics_input inp)

Get the data in the info field of an input.

Parameters

inp – The input to query.

Returns

A string with the info field string.

const char *helicsInputGetInjectionUnits(helics_input ipt)

Get the units of the publication that an input is linked to.

Parameters

ipt – The input to query.

Returns

A void enumeration, helics_ok if everything worked.

int64_t helicsInputGetInteger(helics_input ipt, helics_error *err)

Get an integer value from a subscription.

Parameters

• ipt – The input to get the data for. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

An int64_t value with the current value of the input.

const char *helicsInputGetKey(helics_input ipt)

Get the key of an input.

Parameters

ipt – The input to query.

Returns

A void enumeration, helics_ok if everything worked.

void helicsInputGetNamedPoint(helics_input ipt, char *outputString, int maxStringLength, int *actualLength, double *val, helics_error *err)

Get a named point from a subscription.

@beginPythonOnly

Parameters

• ipt – The input to get the result for. @forcpponly

• outputString – [out] Storage for copying a null terminated string.

• maxStringLength – The maximum size of information that str can hold.

• actualLength – [out] The actual length of the string

• val – [out] The double value for the named point.

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

a string and a double value for the named point @endPythonOnly

int helicsInputGetOption(helics_input inp, int option)

Get the current value of an input handle option

Parameters

• inp – The input to query.

• option – Integer representation of the option in question see /ref helics_handle_options.

Returns

An integer value with the current value of the given option.

const char *helicsInputGetPublicationType(helics_input ipt)

Get the type the publisher to an input is sending.

Parameters

ipt – The input to query.

Returns

A const char * with the type name.

void helicsInputGetRawValue(helics_input ipt, void *data, int maxDataLength, int *actualSize, helics_error *err)

Get the raw data for the latest value of a subscription.

@beginPythonOnly

Parameters

• ipt – The input to get the data for. @forcpponly

• data – [out] The memory location of the data

• maxDataLength – The maximum size of information that data can hold.

• actualSize – [out] The actual length of data copied to data.

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

Raw string data. @endPythonOnly

int helicsInputGetRawValueSize(helics_input ipt)

Get the size of the raw value for subscription.

Returns

The size of the raw data/string in bytes.

void helicsInputGetString(helics_input ipt, char *outputString, int maxStringLength, int *actualLength, helics_error *err)

Get a string value from a subscription.

@beginPythonOnly

Parameters

• ipt – The input to get the data for. @forcpponly

• outputString – [out] Storage for copying a null terminated string.

• maxStringLength – The maximum size of information that str can hold.

• actualLength – [out] The actual length of the string.

• err – [inout] Error term for capturing errors. @endforcpponly

Returns

A string data @endPythonOnly

int helicsInputGetStringSize(helics_input ipt)

Get the size of a value for subscription assuming return as a string.

Returns

The size of the string.

helics_time helicsInputGetTime(helics_input ipt, helics_error *err)

Get a time value from a subscription.

Parameters

• ipt – The input to get the data for. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

The resulting time value.

const char *helicsInputGetType(helics_input ipt)

Get the type of an input.

Parameters

ipt – The input to query.

Returns

A void enumeration, helics_ok if everything worked.

const char *helicsInputGetUnits(helics_input ipt)

Get the units of an input.

Parameters

ipt – The input to query.

Returns

A void enumeration, helics_ok if everything worked.

void helicsInputGetVector(helics_input ipt, double data[], int maxLength, int *actualSize, helics_error *err)

Get a vector from a subscription.

@beginPythonOnly

Parameters

• ipt – The input to get the result for. @forcpponly

• data – [out] The location to store the data.

• maxLength – The maximum size of the vector.

• actualSize – [out] Location to place the actual length of the resulting vector.

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

a list of floating point values @endPythonOnly

int helicsInputGetVectorSize(helics_input ipt)

Get the size of a value for subscription assuming return as an array of doubles.

Returns

The number of doubles in a returned vector.

helics_bool helicsInputIsUpdated(helics_input ipt)

Check if a particular subscription was updated.

Returns

helics_true if it has been updated since the last value retrieval.

helics_bool helicsInputIsValid(helics_input ipt)

Check if an input is valid.

Parameters

ipt – The input to check.

Returns

helics_true if the Input object represents a valid input.

helics_time helicsInputLastUpdateTime(helics_input ipt)

Get the last time a subscription was updated.

void helicsInputSetDefaultBoolean(helics_input ipt, helics_bool val, helics_error *err)

Set the default as a boolean.

Parameters

• ipt – The input to set the default for.

• val – The default boolean value. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsInputSetDefaultChar(helics_input ipt, char val, helics_error *err)

Set the default as a char.

Parameters

• ipt – The input to set the default for.

• val – The default char value. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsInputSetDefaultComplex(helics_input ipt, double real, double imag, helics_error *err)

Set the default as a complex number.

Parameters

• ipt – The input to set the default for.

• real – The default real value.

• imag – The default imaginary value. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsInputSetDefaultDouble(helics_input ipt, double val, helics_error *err)

Set the default as a double.

Parameters

• ipt – The input to set the default for.

• val – The default double value. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsInputSetDefaultInteger(helics_input ipt, int64_t val, helics_error *err)

Set the default as an integer.

Parameters

• ipt – The input to set the default for.

• val – The default integer. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsInputSetDefaultNamedPoint(helics_input ipt, const char *str, double val, helics_error *err)

Set the default as a NamedPoint.

Parameters

• ipt – The input to set the default for.

• str – A pointer to a string representing the name.

• val – A double value for the value of the named point. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsInputSetDefaultRaw(helics_input ipt, const void *data, int inputDataLength, helics_error *err)

Set the default as a raw data array.

Parameters

• ipt – The input to set the default for.

• data – A pointer to the raw data to use for the default. @forcpponly

• inputDataLength – The size of the raw data.

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsInputSetDefaultString(helics_input ipt, const char *str, helics_error *err)

Set the default as a string.

Parameters

• ipt – The input to set the default for.

• str – A pointer to the default string. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsInputSetDefaultTime(helics_input ipt, helics_time val, helics_error *err)

Set the default as a time.

Parameters

• ipt – The input to set the default for.

• val – The default time value. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsInputSetDefaultVector(helics_input ipt, const double *vectorInput, int vectorLength, helics_error *err)

Set the default as a vector of doubles.

Parameters

• ipt – The input to set the default for.

• vectorInput – A pointer to an array of double data.

• vectorLength – The number of points to publish. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsInputSetInfo(helics_input inp, const char *info, helics_error *err)

Set the data in the info field for an input.

Parameters

• inp – The input to query.

• info – The string to set. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsInputSetMinimumChange(helics_input inp, double tolerance, helics_error *err)

Set the minimum change detection tolerance.

Parameters

• inp – The input to modify.

• tolerance – The tolerance level for registering an update, values changing less than this value will not show as being updated. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsInputSetOption(helics_input inp, int option, int value, helics_error *err)

Set an option on an input

Parameters

• inp – The input to query.

• option – The option to set for the input /ref helics_handle_options.

• value – The value to set the option to. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

Message

void helicsMessageAppendData(helics_message_object message, const void *data, int inputDataLength, helics_error *err)

Append data to the payload.

Parameters

• message – The message object in question.

• data – A string containing the message data to append.

• inputDataLength – The length of the data to input. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

helics_bool helicsMessageCheckFlag(helics_message_object message, int flag)

Check if a flag is set on a message.

Parameters

• message – The message object in question.

• flag – The flag to check should be between [0,15].

Returns

The flags associated with a message.

void helicsMessageClearFlags(helics_message_object message)

Clear the flags of a message.

Parameters

message – The message object in question

helics_message_object helicsMessageClone(helics_message_object message, helics_error *err)

Clone a message object.

Parameters

• message – The message object to copy from. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsMessageCopy(helics_message_object src_message, helics_message_object dst_message, helics_error *err)

Copy a message object.

Parameters

• src_message – The message object to copy from.

• dst_message – The message object to copy to. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsMessageFree(helics_message_object message)

Free a message object from memory

memory for message is managed so not using this function does not create memory leaks, this is an indication to the system that the memory for this message is done being used and can be reused for a new message.

helicsFederateClearMessages() can also be used to clear up all stored messages at once

Parameters

message – The message object to copy from.

const char *helicsMessageGetDestination(helics_message_object message)

Get the destination endpoint of a message.

Parameters

message – The message object in question.

Returns

A string with the destination endpoint.

int helicsMessageGetMessageID(helics_message_object message)

Get the messageID of a message.

Parameters

message – The message object in question.

Returns

The messageID.

const char *helicsMessageGetOriginalDestination(helics_message_object message)

Get the original destination endpoint of a message, the destination may have been modified by filters or other actions.

Parameters

message – The message object in question.

Returns

A string with the original destination of a message.

const char *helicsMessageGetOriginalSource(helics_message_object message)

Get the original source endpoint of a message, the source may have been modified by filters or other actions.

Parameters

message – The message object in question.

Returns

A string with the source of a message.

void helicsMessageGetRawData(helics_message_object message, void *data, int maxMessageLength, int *actualSize, helics_error *err)

Get the raw data for a message object.

@beginPythonOnly

Parameters

• message – A message object to get the data for. @forcpponly

• data – [out] The memory location of the data.

• maxMessageLength – The maximum size of information that data can hold.

• actualSize – [out] The actual length of data copied to data.

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

Returns

Raw string data. @endPythonOnly

int helicsMessageGetRawDataSize(helics_message_object message)

Get the size of the data payload in bytes.

Parameters

message – The message object in question.

Returns

The size of the data payload.

const char *helicsMessageGetSource(helics_message_object message)

Get the source endpoint of a message.

Parameters

message – The message object in question.

Returns

A string with the source endpoint.

const char *helicsMessageGetString(helics_message_object message)

Get the payload of a message as a string.

Parameters

message – The message object in question.

Returns

A string representing the payload of a message.

helics_time helicsMessageGetTime(helics_message_object message)

Get the helics time associated with a message.

Parameters

message – The message object in question.

Returns

The time associated with a message.

helics_bool helicsMessageIsValid(helics_message_object message)

A check if the message contains a valid payload.

Parameters

message – The message object in question.

Returns

helics_true if the message contains a payload.

void helicsMessageReserve(helics_message_object message, int reserveSize, helics_error *err)

Reserve space in a buffer but don’t actually resize.

The message data buffer will be reserved but not resized.

Parameters

• message – The message object in question.

• reserveSize – The number of bytes to reserve in the message object. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsMessageSetData(helics_message_object message, const void *data, int inputDataLength, helics_error *err)

Set the data payload of a message as raw data.

Parameters

• message – The message object in question.

• data – A string containing the message data.

• inputDataLength – The length of the data to input. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsMessageSetDestination(helics_message_object message, const char *dst, helics_error *err)

Set the destination of a message.

Parameters

• message – The message object in question.

• dst – A string containing the new destination. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsMessageSetFlagOption(helics_message_object message, int flag, helics_bool flagValue, helics_error *err)

Set a flag on a message.

Parameters

• message – The message object in question.

• flag – An index of a flag to set on the message.

• flagValue – The desired value of the flag. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsMessageSetMessageID(helics_message_object message, int32_t messageID, helics_error *err)

Set the message ID for the message.

Normally this is not needed and the core of HELICS will adjust as needed.

Parameters

• message – The message object in question.

• messageID – A new message ID. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsMessageSetOriginalDestination(helics_message_object message, const char *dst, helics_error *err)

Set the original destination of a message.

Parameters

• message – The message object in question.

• dst – A string containing the new original source. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsMessageSetOriginalSource(helics_message_object message, const char *src, helics_error *err)

Set the original source of a message.

Parameters

• message – The message object in question.

• src – A string containing the new original source. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsMessageSetSource(helics_message_object message, const char *src, helics_error *err)

Set the source of a message.

Parameters

• message – The message object in question.

• src – A string containing the source. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsMessageSetString(helics_message_object message, const char *str, helics_error *err)

Set the data payload of a message as a string.

Parameters

• message – The message object in question.

• str – A string containing the message data. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsMessageSetTime(helics_message_object message, helics_time time, helics_error *err)

Set the delivery time for a message.

Parameters

• message – The message object in question.

• time – The time the message should be delivered. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void *helicsMessageGetRawDataPointer(helics_message_object message)

Get a pointer to the raw data of a message.

Parameters

message – A message object to get the data for.

Returns

A pointer to the raw data in memory, the pointer may be NULL if the message is not a valid message.

Warning

doxygenfunction: Cannot find function “helicsMessageSetOrginalSource” in doxygen xml output for project “helics” from directory: /home/docs/checkouts/readthedocs.org/user_builds/helics/checkouts/helics2/build-doxygen/docs/xml

void helicsMessageResize(helics_message_object message, int newSize, helics_error *err)

Resize the data buffer for a message.

The message data buffer will be resized. There are no guarantees on what is in the buffer in newly allocated space. If the allocated space is not sufficient new allocations will occur.

Parameters

• message – The message object in question.

• newSize – The new size in bytes of the buffer. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

Publication

void helicsPublicationAddTarget(helics_publication pub, const char *target, helics_error *err)

Add a named input to the list of targets a publication publishes to.

Parameters

• pub – The publication to add the target for.

• target – The name of an input that the data should be sent to. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

const char *helicsPublicationGetInfo(helics_publication pub)

Get the data in the info field of an publication.

Parameters

pub – The publication to query.

Returns

A string with the info field string.

const char *helicsPublicationGetKey(helics_publication pub)

Get the key of a publication.

This will be the global key used to identify the publication to the federation.

Parameters

pub – The publication to query.

Returns

A void enumeration, helics_ok if everything worked.

int helicsPublicationGetOption(helics_publication pub, int option)

Get the value of an option for a publication

Parameters

• pub – The publication to query.

• option – The value to query see /ref helics_handle_options.

Returns

A string with the info field string.

const char *helicsPublicationGetType(helics_publication pub)

Get the type of a publication.

Parameters

pub – The publication to query.

Returns

A void enumeration, helics_ok if everything worked.

const char *helicsPublicationGetUnits(helics_publication pub)

Get the units of a publication.

Parameters

pub – The publication to query.

Returns

A void enumeration, helics_ok if everything worked.

helics_bool helicsPublicationIsValid(helics_publication pub)

Check if a publication is valid.

Parameters

pub – The publication to check.

Returns

helics_true if the publication is a valid publication.

void helicsPublicationPublishBoolean(helics_publication pub, helics_bool val, helics_error *err)

Publish a Boolean Value.

Parameters

• pub – The publication to publish for.

• val – The boolean value to publish. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsPublicationPublishChar(helics_publication pub, char val, helics_error *err)

Publish a single character.

Parameters

• pub – The publication to publish for.

• val – The numerical value to publish. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsPublicationPublishComplex(helics_publication pub, double real, double imag, helics_error *err)

Publish a complex value (or pair of values).

Parameters

• pub – The publication to publish for.

• real – The real part of a complex number to publish.

• imag – The imaginary part of a complex number to publish. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsPublicationPublishDouble(helics_publication pub, double val, helics_error *err)

Publish a double floating point value.

Parameters

• pub – The publication to publish for.

• val – The numerical value to publish. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsPublicationPublishInteger(helics_publication pub, int64_t val, helics_error *err)

Publish an integer value.

Parameters

• pub – The publication to publish for.

• val – The numerical value to publish. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsPublicationPublishNamedPoint(helics_publication pub, const char *str, double val, helics_error *err)

Publish a named point.

Parameters

• pub – The publication to publish for.

• str – A string for the name to publish.

• val – A double for the value to publish. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsPublicationPublishRaw(helics_publication pub, const void *data, int inputDataLength, helics_error *err)

Publish raw data from a char * and length.

Parameters

• pub – The publication to publish for.

• data – A pointer to the raw data.

• inputDataLength – The size in bytes of the data to publish. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsPublicationPublishString(helics_publication pub, const char *str, helics_error *err)

Publish a string.

Parameters

• pub – The publication to publish for.

• str – The string to publish. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsPublicationPublishTime(helics_publication pub, helics_time val, helics_error *err)

Publish a time value.

Parameters

• pub – The publication to publish for.

• val – The numerical value to publish. @forcpponly

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsPublicationPublishVector(helics_publication pub, const double *vectorInput, int vectorLength, helics_error *err)

Publish a vector of doubles.

Parameters

• pub – The publication to publish for.

• vectorInput – A pointer to an array of double data. @forcpponly

• vectorLength – The number of points to publish.

• err – [inout] A pointer to an error object for catching errors. @endforcpponly

void helicsPublicationSetInfo(helics_publication pub, const char *info, helics_error *err)

Set the data in the info field for a publication.

Parameters

• pub – The publication to set the info field for.

• info – The string to set. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsPublicationSetMinimumChange(helics_publication pub, double tolerance, helics_error *err)

Set the minimum change detection tolerance.

Parameters

• pub – The publication to modify.

• tolerance – The tolerance level for publication, values changing less than this value will not be published. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

void helicsPublicationSetOption(helics_publication pub, int option, int val, helics_error *err)

Set the value of an option for a publication

Parameters

• pub – The publication to query.

• option – Integer code for the option to set /ref helics_handle_options.

• val – The value to set the option to. @forcpponly

• err – [inout] An error object to fill out in case of an error. @endforcpponly

Query

const char *helicsQueryBrokerExecute(helics_query query, helics_broker broker, helics_error *err)

Execute a query directly on a broker.

The call will block until the query finishes which may require communication or other delays.

Parameters

• query – The query object to use in the query.

• broker – The broker to send the query to. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

A pointer to a string. The string will remain valid until the query is freed or executed again. @forcpponly The return will be nullptr if broker or query is an invalid object, the return string will be “#invalid” if the query itself was invalid @endforcpponly

const char *helicsQueryCoreExecute(helics_query query, helics_core core, helics_error *err)

Execute a query directly on a core.

The call will block until the query finishes which may require communication or other delays.

Parameters

• query – The query object to use in the query.

• core – The core to send the query to. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

A pointer to a string. The string will remain valid until the query is freed or executed again. @forcpponly The return will be nullptr if core or query is an invalid object, the return string will be “#invalid” if the query itself was invalid. @endforcpponly

const char *helicsQueryExecute(helics_query query, helics_federate fed, helics_error *err)

Execute a query.

The call will block until the query finishes which may require communication or other delays.

Parameters

• query – The query object to use in the query.

• fed – A federate to send the query through. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

A pointer to a string. The string will remain valid until the query is freed or executed again. @forcpponly The return will be nullptr if fed or query is an invalid object, the return string will be “#invalid” if the query itself was invalid. @endforcpponly

void helicsQueryExecuteAsync(helics_query query, helics_federate fed, helics_error *err)

Execute a query in a non-blocking call.

Parameters

• query – The query object to use in the query.

• fed – A federate to send the query through. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

const char *helicsQueryExecuteComplete(helics_query query, helics_error *err)

Complete the return from a query called with /ref helicsExecuteQueryAsync.

The function will block until the query completes /ref isQueryComplete can be called to determine if a query has completed or not.

Parameters

• query – The query object to complete execution of. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

A pointer to a string. The string will remain valid until the query is freed or executed again. @forcpponly The return will be nullptr if query is an invalid object @endforcpponly

void helicsQueryFree(helics_query query)

Free the memory associated with a query object.

helics_bool helicsQueryIsCompleted(helics_query query)

Check if an asynchronously executed query has completed.

This function should usually be called after a QueryExecuteAsync function has been called.

Parameters

query – The query object to check if completed.

Returns

Will return helics_true if an asynchronous query has completed or a regular query call was made with a result, and false if an asynchronous query has not completed or is invalid

Warning

doxygenfunction: Cannot find function “helicsQueryExecuteCompleted” in doxygen xml output for project “helics” from directory: /home/docs/checkouts/readthedocs.org/user_builds/helics/checkouts/helics2/build-doxygen/docs/xml

void helicsQuerySetTarget(helics_query query, const char *target, helics_error *err)

Update the target of a query.

@forcpponly

Parameters

• query – The query object to change the target of.

• target – the name of the target to query

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

void helicsQuerySetQueryString(helics_query query, const char *queryString, helics_error *err)

Update the queryString of a query.

Parameters

• query – The query object to change the target of.

• queryString – the new queryString @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Others

void helicsCleanupLibrary(void)

Function to do some housekeeping work.

This runs some cleanup routines and tries to close out any residual thread that haven’t been shutdown yet.

void helicsCloseLibrary(void)

Call when done using the helics library. This function will ensure the threads are closed properly. If possible this should be the last call before exiting.

helics_broker helicsCreateBroker(const char *type, const char *name, const char *initString, helics_error *err)

Create a broker object.

Parameters

• type – The type of the broker to create.

• name – The name of the broker. It can be a nullptr or empty string to have a name automatically assigned.

• initString – An initialization string to send to the core-the format is similar to command line arguments. Typical options include a broker address such as broker=”XSSAF” if this is a subbroker, or the number of federates, or the address. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

A helics_broker object. @forcpponly It will be NULL if there was an error indicated in the err object. @endforcpponly

helics_broker helicsCreateBrokerFromArgs(const char *type, const char *name, int argc, const char *const *argv, helics_error *err)

Create a core object by passing command line arguments.

Parameters

• type – The type of the core to create.

• name – The name of the core. It can be a nullptr or empty string to have a name automatically assigned. @forcpponly

• argc – The number of arguments. @endforcpponly

• argv – The list of string values from a command line. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

A helics_core object.

helics_federate helicsCreateCombinationFederate(const char *fedName, helics_federate_info fi, helics_error *err)

Create a combination federate from a federate info object.

Combination federates are both value federates and message federates, objects can be used in all functions that take a helics_federate, helics_message_federate or helics_federate object as an argument

Parameters

• fedName – A string with the name of the federate, can be NULL or an empty string to pull the default name from fi.

• fi – The federate info object that contains details on the federate. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

An opaque value federate object nullptr if the object creation failed.

helics_federate helicsCreateCombinationFederateFromConfig(const char *configFile, helics_error *err)

Create a combination federate from a JSON file or JSON string or TOML file.

Combination federates are both value federates and message federates, objects can be used in all functions that take a helics_federate, helics_message_federate or helics_federate object as an argument

Parameters

• configFile – A JSON file or a JSON string or TOML file that contains setup and configuration information. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

An opaque combination federate object.

helics_core helicsCreateCore(const char *type, const char *name, const char *initString, helics_error *err)

Create a core object.

Parameters

• type – The type of the core to create.

• name – The name of the core. It can be a nullptr or empty string to have a name automatically assigned.

• initString – An initialization string to send to the core. The format is similar to command line arguments. Typical options include a broker name, the broker address, the number of federates, etc. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

A helics_core object. @forcpponly If the core is invalid, err will contain the corresponding error message and the returned object will be NULL. @endforcpponly

helics_core helicsCreateCoreFromArgs(const char *type, const char *name, int argc, const char *const *argv, helics_error *err)

Create a core object by passing command line arguments.

Parameters

• type – The type of the core to create.

• name – The name of the core. It can be a nullptr or empty string to have a name automatically assigned. @forcpponly

• argc – The number of arguments. @endforcpponly

• argv – The list of string values from a command line. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

A helics_core object.

helics_federate_info helicsCreateFederateInfo(void)

Create a federate info object for specifying federate information when constructing a federate.

Returns

A helics_federate_info object which is a reference to the created object.

helics_federate helicsCreateMessageFederate(const char *fedName, helics_federate_info fi, helics_error *err)

Create a message federate from a federate info object.

helics_message_federate objects can be used in all functions that take a helics_message_federate or helics_federate object as an argument.

Parameters

• fedName – The name of the federate to create.

• fi – The federate info object that contains details on the federate. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

An opaque message federate object.

helics_federate helicsCreateMessageFederateFromConfig(const char *configFile, helics_error *err)

Create a message federate from a JSON file or JSON string or TOML file.

helics_message_federate objects can be used in all functions that take a helics_message_federate or helics_federate object as an argument.

Parameters

• configFile – A Config(JSON,TOML) file or a JSON string that contains setup and configuration information. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

An opaque message federate object.

helics_query helicsCreateQuery(const char *target, const char *query)

Create a query object.

A query object consists of a target and query string.

Parameters

• target – The name of the target to query.

• query – The query to make of the target.

helics_federate helicsCreateValueFederate(const char *fedName, helics_federate_info fi, helics_error *err)

Create a value federate from a federate info object.

helics_federate objects can be used in all functions that take a helics_federate or helics_federate object as an argument.

Parameters

• fedName – The name of the federate to create, can NULL or an empty string to use the default name from fi or an assigned name.

• fi – The federate info object that contains details on the federate. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

An opaque value federate object.

helics_federate helicsCreateValueFederateFromConfig(const char *configFile, helics_error *err)

Create a value federate from a JSON file, JSON string, or TOML file.

helics_federate objects can be used in all functions that take a helics_federate or helics_federate object as an argument.

Parameters

• configFile – A JSON file or a JSON string or TOML file that contains setup and configuration information. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

An opaque value federate object.

const char *helicsGetBuildFlags(void)

Get the build flags used to compile HELICS.

const char *helicsGetCompilerVersion(void)

Get the compiler version used to compile HELICS.

helics_federate helicsGetFederateByName(const char *fedName, helics_error *err)

Get an existing federate object from a core by name.

The federate must have been created by one of the other functions and at least one of the objects referencing the created federate must still be active in the process.

Parameters

• fedName – The name of the federate to retrieve. @forcpponly

• err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly

Returns

NULL if no fed is available by that name otherwise a helics_federate with that name.

int helicsGetOptionIndex(const char *val)

Get an option index for use in /ref helicsPublicationSetOption, /ref helicsInputSetOption, /ref helicsEndpointSetOption, /ref helicsFilterSetOption, and the corresponding get functions.

Parameters

val – A string with the option name.

Returns

An int with the option index or (-1) if not a valid property.

int helicsGetPropertyIndex(const char *val)

Get a property index for use in /ref helicsFederateInfoSetFlagOption, /ref helicsFederateInfoSetTimeProperty, or /ref helicsFederateInfoSetIntegerProperty

Parameters

val – A string with the property name.

Returns

An int with the property code or (-1) if not a valid property.

const char *helicsGetVersion(void)

Get a version string for HELICS.

helics_bool helicsIsCoreTypeAvailable(const char *type)

Returns true if core/broker type specified is available in current compilation.

Options include “zmq”, “udp”, “ipc”, “interprocess”, “tcp”, “default”, “mpi”.

Parameters

type – A string representing a core type.

const char *helicsSubscriptionGetKey(helics_input ipt)

Get the key of a subscription.

Returns

A const char with the subscription key.

helics_error helicsErrorInitialize(void)

Return an initialized error object.

void helicsErrorClear(helics_error *err)

Clear an error object.

clear an error object