C API Reference

Table of Contents

  1. Enums

  2. General function

  3. Creation functions

  4. Broker methods

  5. Core methods

  6. FederateInfo methods

  7. Federate methods

  8. ValueFederate

  9. Publication methods

  10. Input methods

  11. MessageFederate methods

  12. Endpoint methods

  13. Message object methods

  14. FilterFederate methods

  15. Filter methods

  16. Query methods

Enums

enumerator HELICS_ITERATION_REQUEST_NO_ITERATION

no iteration is requested

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_RESULT_NEXT_STEP

the iterations have progressed to the next time

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_STATE_STARTUP

when created the federate is in startup state

enumerator HELICS_STATE_INITIALIZATION

entered after the enterInitializingMode call has returned

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_ERROR

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

enumerator HELICS_STATE_PENDING_INIT

indicator that the federate is pending entry to initialization state

enumerator HELICS_STATE_PENDING_EXEC

state pending EnterExecution State

enumerator HELICS_STATE_PENDING_TIME

state that the federate is pending a timeRequest

enumerator HELICS_STATE_PENDING_ITERATIVE_TIME

state that the federate is pending an iterative time request

enumerator HELICS_STATE_PENDING_FINALIZE

state that the federate is pending a finalize request

enumerator HELICS_STATE_FINISHED

state that the federate is finished simulating but still connected

enumerator HELICS_CORE_TYPE_DEFAULT

a default core type that will default to something available

enumerator HELICS_CORE_TYPE_ZMQ

use the Zero MQ networking protocol

enumerator HELICS_CORE_TYPE_MPI

use MPI for operation on a parallel cluster

enumerator HELICS_CORE_TYPE_TEST

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

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_TCP

use a generic TCP protocol message stream to send messages

enumerator HELICS_CORE_TYPE_UDP

use UDP packets to send the data

enumerator HELICS_CORE_TYPE_ZMQ_SS

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

enumerator HELICS_CORE_TYPE_NNG

for using the nanomsg communications

enumerator HELICS_CORE_TYPE_TCP_SS

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

enumerator HELICS_CORE_TYPE_HTTP

a core type using http for communication

enumerator HELICS_CORE_TYPE_WEBSOCKET

a core using websockets 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_NULL

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

enumerator HELICS_DATA_TYPE_STRING

a sequence of characters

enumerator HELICS_DATA_TYPE_DOUBLE

a double precision floating point number

enumerator HELICS_DATA_TYPE_INT

a 64 bit integer

enumerator HELICS_DATA_TYPE_COMPLEX

a pair of doubles representing a complex number

enumerator HELICS_DATA_TYPE_VECTOR

an array of doubles

enumerator HELICS_DATA_TYPE_COMPLEX_VECTOR

a complex vector object

enumerator HELICS_DATA_TYPE_NAMED_POINT

a named point consisting of a string and a double

enumerator HELICS_DATA_TYPE_BOOLEAN

a boolean data type

enumerator HELICS_DATA_TYPE_TIME

time data type

enumerator HELICS_DATA_TYPE_RAW

raw data type

enumerator HELICS_DATA_TYPE_JSON

type converts to a valid json string

enumerator HELICS_DATA_TYPE_MULTI

the data type can change

enumerator HELICS_DATA_TYPE_ANY

open type that can be anything

enumerator HELICS_FLAG_OBSERVER

flag indicating that a federate is observe only

enumerator HELICS_FLAG_UNINTERRUPTIBLE

flag indicating that a federate can only return requested times

enumerator HELICS_FLAG_INTERRUPTIBLE

flag indicating that a federate can be interrupted

enumerator HELICS_FLAG_SOURCE_ONLY

flag indicating that a federate/interface is a signal generator 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_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_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_FORWARD_COMPUTE

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

enumerator HELICS_FLAG_REALTIME

flag indicating that a federate needs to run in real time

enumerator HELICS_FLAG_SINGLE_THREAD_FEDERATE

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

enumerator HELICS_FLAG_IGNORE_TIME_MISMATCH_WARNINGS

used to not display warnings on mismatched requested times

enumerator HELICS_FLAG_STRICT_CONFIG_CHECKING

specify that checking on configuration files should be strict and throw and error on any invalid values

enumerator HELICS_FLAG_USE_JSON_SERIALIZATION

specify that the federate should use json serialization for all data types

enumerator HELICS_FLAG_EVENT_TRIGGERED

specify that the federate is event triggered-meaning (all/most) events are triggered by incoming events

enumerator HELICS_FLAG_LOCAL_PROFILING_CAPTURE

specify that that federate should capture the profiling data to the local federate logging system

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_IGNORE

ignored flag used to test some code paths

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_DEBUGGING

flag specifying the federate/core/broker is operating in a user debug mode so deadlock timers and timeout are disabled this flag is a combination of slow_responding and disabling of some timeouts

enumerator HELICS_FLAG_TERMINATE_ON_ERROR

specify that a federate error should terminate the federation

enumerator HELICS_FLAG_FORCE_LOGGING_FLUSH

specify that the log files should be flushed on every log message

enumerator HELICS_FLAG_DUMPLOG

specify that a full log should be dumped into a file

enumerator HELICS_FLAG_PROFILING

specify that helics should capture profiling data

enumerator HELICS_FLAG_PROFILING_MARKER

flag trigger for generating a profiling marker

enumerator HELICS_LOG_LEVEL_NO_PRINT

don’t print anything except a few catastrophic errors

enumerator HELICS_LOG_LEVEL_ERROR

only print error level indicators

enumerator HELICS_LOG_LEVEL_PROFILING

profiling log level

enumerator HELICS_LOG_LEVEL_WARNING

only print warnings and errors

enumerator HELICS_LOG_LEVEL_SUMMARY

warning errors and summary level information

enumerator HELICS_LOG_LEVEL_CONNECTIONS

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

enumerator HELICS_LOG_LEVEL_INTERFACES

connections+ interface definitions

enumerator HELICS_LOG_LEVEL_TIMING

interfaces + timing message

enumerator HELICS_LOG_LEVEL_DATA

timing+ data transfer notices

enumerator HELICS_LOG_LEVEL_DEBUG

data+ additional debug message

enumerator HELICS_LOG_LEVEL_TRACE

all internal messages

enumerator HELICS_ERROR_FATAL

global fatal error for federation

enumerator HELICS_ERROR_EXTERNAL_TYPE

an unknown non-helics error was produced

enumerator HELICS_ERROR_OTHER

the function produced a helics error of some other type

enumerator HELICS_ERROR_USER_ABORT

user system abort

enumerator HELICS_ERROR_INSUFFICIENT_SPACE

insufficient space is available to store requested data

enumerator HELICS_ERROR_EXECUTION_FAILURE

the function execution has failed

enumerator HELICS_ERROR_INVALID_FUNCTION_CALL

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

enumerator HELICS_ERROR_INVALID_STATE_TRANSITION

error issued when an invalid state transition occurred

enumerator HELICS_ERROR_SYSTEM_FAILURE

the federate has terminated unexpectedly and the call cannot be completed

enumerator HELICS_ERROR_DISCARD

the input was discarded and not used for some reason

enumerator HELICS_ERROR_INVALID_ARGUMENT

the parameter passed was invalid and unable to be used

enumerator HELICS_ERROR_INVALID_OBJECT

indicator that the object used was not a valid object

enumerator HELICS_ERROR_CONNECTION_FAILURE

the operation to connect has failed

enumerator HELICS_ERROR_REGISTRATION_FAILURE

registration has failed

enumerator HELICS_PROPERTY_TIME_DELTA

the property controlling the minimum time delta for a federate

enumerator HELICS_PROPERTY_TIME_PERIOD

the property controlling the period for a federate

enumerator HELICS_PROPERTY_TIME_OFFSET

the property controlling time offset for the period of 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_PROPERTY_TIME_INPUT_DELAY

the property controlling input delay for a federate

enumerator HELICS_PROPERTY_TIME_OUTPUT_DELAY

the property controlling output delay for a federate

enumerator HELICS_PROPERTY_INT_MAX_ITERATIONS

integer property controlling the maximum number of iterations in a federate

enumerator HELICS_PROPERTY_INT_LOG_LEVEL

integer property controlling the log level in a federate see HelicsLogLevels

enumerator HELICS_PROPERTY_INT_FILE_LOG_LEVEL

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

enumerator HELICS_PROPERTY_INT_CONSOLE_LOG_LEVEL

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

enumerator HELICS_MULTI_INPUT_NO_OP

time and priority order the inputs from the core library

enumerator HELICS_MULTI_INPUT_VECTORIZE_OPERATION

vectorize the inputs either double vector or string vector

enumerator HELICS_MULTI_INPUT_AND_OPERATION

all inputs are assumed to be boolean and all must be true to return true

enumerator HELICS_MULTI_INPUT_OR_OPERATION

all inputs are assumed to be boolean and at least one must be true to return true

enumerator HELICS_MULTI_INPUT_SUM_OPERATION

sum all the inputs

enumerator HELICS_MULTI_INPUT_DIFF_OPERATION

do a difference operation on the inputs, first-sum(rest) for double input, vector diff for vector input

enumerator HELICS_MULTI_INPUT_MAX_OPERATION

find the max of the inputs

enumerator HELICS_MULTI_INPUT_MIN_OPERATION

find the min of the inputs

enumerator HELICS_MULTI_INPUT_AVERAGE_OPERATION

take the average of the inputs

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_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_SINGLE_CONNECTION_ONLY

specify that only a single connection is allowed for an interface

enumerator HELICS_HANDLE_OPTION_MULTIPLE_CONNECTIONS_ALLOWED

specify that multiple connections are allowed for an interface

enumerator HELICS_HANDLE_OPTION_BUFFER_DATA

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

enumerator HELICS_HANDLE_OPTION_STRICT_TYPE_CHECKING

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

enumerator HELICS_HANDLE_OPTION_IGNORE_UNIT_MISMATCH

specify that the mismatching units should be ignored

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_IGNORE_INTERRUPTS

specify that an interface does not participate in determining time interrupts

enumerator HELICS_HANDLE_OPTION_MULTI_INPUT_HANDLING_METHOD

specify the multi-input processing method for inputs

enumerator HELICS_HANDLE_OPTION_INPUT_PRIORITY_LOCATION

specify the source index with the highest priority

enumerator HELICS_HANDLE_OPTION_CLEAR_PRIORITY_LIST

specify that the priority list should be cleared or question if it is cleared

enumerator HELICS_HANDLE_OPTION_CONNECTIONS

specify the required number of connections or get the actual number of connections

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_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_FILTER_TYPE_CLONE

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

enumerator HELICS_FILTER_TYPE_FIREWALL

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

enumerator HELICS_SEQUENCING_MODE_FAST

sequencing mode to operate on priority channels

enumerator HELICS_SEQUENCING_MODE_ORDERED

sequencing mode to operate on the normal channels

enumerator HELICS_SEQUENCING_MODE_DEFAULT

select the default channel

General

const char *helicsGetVersion(void)

Get a version string for HELICS.

const char *helicsGetBuildFlags(void)

Get the build flags used to compile HELICS.

const char *helicsGetCompilerVersion(void)

Get the compiler version used to compile HELICS.

HelicsError helicsErrorInitialize(void)

Return an initialized error object.

void helicsErrorClear(HelicsError *err)

Clear an error object.

clear an error object

void helicsLoadSignalHandler()

Load a signal handler that handles Ctrl-C and shuts down all HELICS brokers, cores, and federates then exits the process.

void helicsClearSignalHandler()

Clear HELICS based signal handlers.

void helicsLoadSignalHandlerCallback(HelicsBool (*handler)(int))

Load a custom signal handler to execute prior to the abort signal handler.

This function is not 100% reliable it will most likely work but uses some functions and techniques that are not 100% guaranteed to work in a signal handler and in worst case it could deadlock. That is somewhat unlikely given usage patterns but it is possible. The callback has signature helics_bool(*handler)(int) and it will take the SIG_INT as an argument and return a boolean. If the boolean return value is helics_true (or the callback is null) the default signal handler is run after the callback finishes; if it is helics_false the default callback is not run and the default signal handler is executed.

void helicsAbort(int errorCode, const char *errorString)

Execute a global abort by sending an error code to all cores, brokers, and federates that were created through the current library instance.

HelicsBool 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.

HelicsFederate helicsGetFederateByName(const char *fedName, HelicsError *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.

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

Returns

NULL if no fed is available by that name otherwise a HelicsFederate with that name.

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.

int helicsGetFlagIndex(const char *val)

Get a property index for use in /ref helicsFederateInfoSetFlagOption, /ref helicsFederateSetFlagOption,

Parameters

val – A string with the option name.

Returns

An int with the property code or (-1) if not a valid property.

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 helicsGetOptionValue(const char *val)

Get an option value for use in /ref helicsPublicationSetOption, /ref helicsInputSetOption, /ref helicsEndpointSetOption, /ref helicsFilterSetOption.

Parameters

val – A string representing the value.

Returns

An int with the option value or (-1) if not a valid value.

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.

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.

Creation

HelicsCore helicsCreateCore(const char *type, const char *name, const char *initString, HelicsError *err)

Create a core object.

If the core is invalid, err will contain the corresponding error message and the returned object will be NULL.

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.

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

Returns

A HelicsCore object.

HelicsCore helicsCreateCoreFromArgs(const char *type, const char *name, int argc, const char *const *argv, HelicsError *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.

  • argc – The number of arguments.

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

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

Returns

A HelicsCore object.

HelicsBroker helicsCreateBroker(const char *type, const char *name, const char *initString, HelicsError *err)

Create a broker object.

It will be NULL if there was an error indicated in the err 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.

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

Returns

A HelicsBroker object.

HelicsBroker helicsCreateBrokerFromArgs(const char *type, const char *name, int argc, const char *const *argv, HelicsError *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.

  • argc – The number of arguments.

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

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

Returns

A HelicsCore object.

HelicsFederate helicsCreateValueFederate(const char *fedName, HelicsFederateInfo fi, HelicsError *err)

Create a value federate from a federate info object.

HelicsFederate objects can be used in all functions that take a HelicsFederate or HelicsFederate 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.

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

Returns

An opaque value federate object.

HelicsFederate helicsCreateValueFederateFromConfig(const char *configFile, HelicsError *err)

Create a value federate from a JSON file, JSON string, or TOML file.

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

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

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

Returns

An opaque value federate object.

HelicsFederate helicsCreateMessageFederate(const char *fedName, HelicsFederateInfo fi, HelicsError *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 HelicsFederate object as an argument.

Parameters
  • fedName – The name of the federate to create.

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

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

Returns

An opaque message federate object.

HelicsFederate helicsCreateMessageFederateFromConfig(const char *configFile, HelicsError *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 HelicsFederate object as an argument.

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

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

Returns

An opaque message federate object.

HelicsFederate helicsCreateCombinationFederate(const char *fedName, HelicsFederateInfo fi, HelicsError *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 HelicsFederate, helics_message_federate or HelicsFederate 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.

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

Returns

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

HelicsFederate helicsCreateCombinationFederateFromConfig(const char *configFile, HelicsError *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 HelicsFederate, helics_message_federate or HelicsFederate object as an argument

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

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

Returns

An opaque combination federate object.

HelicsFederateInfo helicsCreateFederateInfo(void)

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

Returns

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

HelicsQuery 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.

Broker

HelicsBroker helicsBrokerClone(HelicsBroker broker, HelicsError *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 HelicsBroker.

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

Returns

A new reference to the same broker.

HelicsBool helicsBrokerIsValid(HelicsBroker broker)

Check if a broker object is a valid object.

Parameters

broker – The HelicsBroker object to test.

HelicsBool helicsBrokerIsConnected(HelicsBroker 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.

void helicsBrokerDataLink(HelicsBroker broker, const char *source, const char *target, HelicsError *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).

  • err[inout] A HelicsError object, can be NULL if the errors are to be ignored.

void helicsBrokerAddSourceFilterToEndpoint(HelicsBroker broker, const char *filter, const char *endpoint, HelicsError *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).

  • err[inout] A HelicsError object, can be NULL if the errors are to be ignored.

void helicsBrokerAddDestinationFilterToEndpoint(HelicsBroker broker, const char *filter, const char *endpoint, HelicsError *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).

  • err[inout] A HelicsError object, can be NULL if the errors are to be ignored.

void helicsBrokerMakeConnections(HelicsBroker broker, const char *file, HelicsError *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.

  • err[inout] A HelicsError object, can be NULL if the errors are to be ignored.

HelicsBool helicsBrokerWaitForDisconnect(HelicsBroker broker, int msToWait, HelicsError *err)

Wait for the broker to disconnect.

Parameters
  • broker – The broker to wait for.

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

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

Returns

HELICS_TRUE if the disconnect was successful, HELICS_FALSE if there was a timeout.

const char *helicsBrokerGetIdentifier(HelicsBroker broker)

Get an identifier for the broker.

Parameters

broker – The broker to query.

Returns

A string containing the identifier for the broker.

const char *helicsBrokerGetAddress(HelicsBroker 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.

void helicsBrokerDisconnect(HelicsBroker broker, HelicsError *err)

Disconnect a broker.

Parameters
  • broker – The broker to disconnect.

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

void helicsBrokerDestroy(HelicsBroker broker)

Disconnect and free a broker.

void helicsBrokerFree(HelicsBroker broker)

Release the memory associated with a broker.

void helicsBrokerSetGlobal(HelicsBroker broker, const char *valueName, const char *value, HelicsError *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.

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

void helicsBrokerSendCommand(HelicsBroker broker, const char *target, const char *command, HelicsError *err)

Send a command to another helics object through a broker.

Parameters
  • broker – The broker to send the command through.

  • target – The name of the object to send the command to.

  • command – The command to send.

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

void helicsBrokerSetLogFile(HelicsBroker broker, const char *logFileName, HelicsError *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.

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

void helicsBrokerSetTimeBarrier(HelicsBroker broker, HelicsTime barrierTime, HelicsError *err)

Set a broker time barrier.

Parameters
  • broker – The broker to set the time barrier for.

  • barrierTime – The time to set the barrier at.

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

void helicsBrokerClearTimeBarrier(HelicsBroker broker)

Clear any time barrier on a broker.

Parameters

broker – The broker to clear the barriers on.

void helicsBrokerGlobalError(HelicsBroker broker, int errorCode, const char *errorString, HelicsError *err)

Generate a global error through a broker. This will terminate the federation.

Parameters
  • broker – The broker to generate the global error on.

  • errorCode – The error code to associate with the global error.

  • errorString – An error message to associate with the global error.

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

void helicsBrokerSetLoggingCallback(HelicsBroker broker, void (*logger)(int loglevel, const char *identifier, const char *message, void *userData), void *userdata, HelicsError *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.

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

Core

HelicsCore helicsCoreClone(HelicsCore core, HelicsError *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 HelicsCore.

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

Returns

A new reference to the same broker.

HelicsBool helicsCoreIsValid(HelicsCore core)

Check if a core object is a valid object.

Parameters

core – The HelicsCore object to test.

HelicsBool helicsCoreWaitForDisconnect(HelicsCore core, int msToWait, HelicsError *err)

Wait for the core to disconnect.

Parameters
  • core – The core to wait for.

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

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

Returns

HELICS_TRUE if the disconnect was successful, HELICS_FALSE if there was a timeout.

HelicsBool helicsCoreIsConnected(HelicsCore 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.

void helicsCoreDataLink(HelicsCore core, const char *source, const char *target, HelicsError *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).

  • err[inout] A HelicsError object, can be NULL if the errors are to be ignored.

void helicsCoreAddSourceFilterToEndpoint(HelicsCore core, const char *filter, const char *endpoint, HelicsError *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).

  • err[inout] A HelicsError object, can be NULL if the errors are to be ignored.

void helicsCoreAddDestinationFilterToEndpoint(HelicsCore core, const char *filter, const char *endpoint, HelicsError *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).

  • err[inout] A HelicsError object, can be NULL if the errors are to be ignored.

void helicsCoreMakeConnections(HelicsCore core, const char *file, HelicsError *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.

  • err[inout] A HelicsError object, can be NULL if the errors are to be ignored.

const char *helicsCoreGetIdentifier(HelicsCore core)

Get an identifier for the core.

Parameters

core – The core to query.

Returns

A string with the identifier of the core.

const char *helicsCoreGetAddress(HelicsCore 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.

void helicsCoreSetReadyToInit(HelicsCore core, HelicsError *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.

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

HelicsBool helicsCoreConnect(HelicsCore core, HelicsError *err)

Connect a core to the federate based on current configuration.

Parameters
  • core – The core to connect.

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

Returns

HELICS_FALSE if not connected, HELICS_TRUE if it is connected.

void helicsCoreDisconnect(HelicsCore core, HelicsError *err)

Disconnect a core from the federation.

Parameters
  • core – The core 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.

void helicsCoreDestroy(HelicsCore core)

Disconnect and free a core.

void helicsCoreFree(HelicsCore core)

Release the memory associated with a core.

void helicsCoreSetGlobal(HelicsCore core, const char *valueName, const char *value, HelicsError *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.

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

void helicsCoreSendCommand(HelicsCore core, const char *target, const char *command, HelicsError *err)

Send a command to another helics object though a core.

Parameters
  • core – The core to send the command through.

  • target – The name of the object to send the command to.

  • command – The command to send.

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

void helicsCoreSetLogFile(HelicsCore core, const char *logFileName, HelicsError *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.

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

void helicsCoreGlobalError(HelicsCore core, int errorCode, const char *errorString, HelicsError *err)

Generate a global error through a broker. This will terminate the federation.

Parameters
  • core – The core to generate the global error.

  • errorCode – The error code to associate with the global error.

  • errorString – An error message to associate with the global error.

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

void helicsCoreSetLoggingCallback(HelicsCore core, void (*logger)(int loglevel, const char *identifier, const char *message, void *userData), void *userdata, HelicsError *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.

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

HelicsFilter helicsCoreRegisterFilter(HelicsCore core, HelicsFilterTypes type, const char *name, HelicsError *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 HelicsFilterTypes.

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

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

Returns

A HelicsFilter object.

HelicsFilter helicsCoreRegisterCloningFilter(HelicsCore core, const char *name, HelicsError *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).

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

Returns

A HelicsFilter object.

FederateInfo

HelicsFederateInfo helicsFederateInfoClone(HelicsFederateInfo fi, HelicsError *err)

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

Parameters
  • fi – A federateInfo object to duplicate.

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

Returns

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

void helicsFederateInfoLoadFromArgs(HelicsFederateInfo fi, int argc, const char *const *argv, HelicsError *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.

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

void helicsFederateInfoFree(HelicsFederateInfo fi)

Delete the memory associated with a federate info object.

void helicsFederateInfoSetCoreName(HelicsFederateInfo fi, const char *corename, HelicsError *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.

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

void helicsFederateInfoSetCoreInitString(HelicsFederateInfo fi, const char *coreInit, HelicsError *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.

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

void helicsFederateInfoSetBrokerInitString(HelicsFederateInfo fi, const char *brokerInit, HelicsError *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.

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

void helicsFederateInfoSetCoreType(HelicsFederateInfo fi, int coretype, HelicsError *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_CoreType.

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

void helicsFederateInfoSetCoreTypeFromString(HelicsFederateInfo fi, const char *coretype, HelicsError *err)

Set the core type from a string.

Parameters
  • fi – The federate info object to alter.

  • coretype – A string naming a core type.

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

void helicsFederateInfoSetBroker(HelicsFederateInfo fi, const char *broker, HelicsError *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.

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

void helicsFederateInfoSetBrokerKey(HelicsFederateInfo fi, const char *brokerkey, HelicsError *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.

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

void helicsFederateInfoSetBrokerPort(HelicsFederateInfo fi, int brokerPort, HelicsError *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.

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

void helicsFederateInfoSetLocalPort(HelicsFederateInfo fi, const char *localPort, HelicsError *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”.

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

void helicsFederateInfoSetFlagOption(HelicsFederateInfo fi, int flag, HelicsBool value, HelicsError *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.

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

void helicsFederateInfoSetSeparator(HelicsFederateInfo fi, char separator, HelicsError *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.

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

void helicsFederateInfoSetTimeProperty(HelicsFederateInfo fi, int timeProperty, HelicsTime propertyValue, HelicsError *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.

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

void helicsFederateInfoSetIntegerProperty(HelicsFederateInfo fi, int intProperty, int propertyValue, HelicsError *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.

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

Federate

void helicsFederateDestroy(HelicsFederate fed)

Disconnect and free a federate.

HelicsFederate helicsFederateClone(HelicsFederate fed, HelicsError *err)

Create a new reference to an existing federate.

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

Parameters
  • fed – An existing HelicsFederate.

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

Returns

A new reference to the same federate.

HelicsBool helicsFederateIsValid(HelicsFederate fed)

Check if a federate_object is valid.

Returns

HELICS_TRUE if the federate is a valid active federate, HELICS_FALSE otherwise

void helicsFederateRegisterInterfaces(HelicsFederate fed, const char *file, HelicsError *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.

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

void helicsFederateGlobalError(HelicsFederate fed, int errorCode, const char *errorString, HelicsError *err)

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.

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

void helicsFederateLocalError(HelicsFederate fed, int errorCode, const char *errorString, HelicsError *err)

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.

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

void helicsFederateFinalize(HelicsFederate fed, HelicsError *err)

Disconnect/finalize the federate. This function halts all communication in the federate and disconnects it from the core.

void helicsFederateFinalizeAsync(HelicsFederate fed, HelicsError *err)

Disconnect/finalize the federate in an async call.

void helicsFederateFinalizeComplete(HelicsFederate fed, HelicsError *err)

Complete the asynchronous disconnect/finalize call.

void helicsFederateDisconnect(HelicsFederate fed, HelicsError *err)

Disconnect/finalize the federate. This function halts all communication in the federate and disconnects it from the core. This call is identical to helicsFederateFinalize.

void helicsFederateDisconnectAsync(HelicsFederate fed, HelicsError *err)

Disconnect/finalize the federate in an async call. This call is identical to helicsFederateFinalizeAsync.

void helicsFederateDisconnectComplete(HelicsFederate fed, HelicsError *err)

Complete the asynchronous disconnect/finalize call. This call is identical to helicsFederateFinalizeComplete

void helicsFederateFree(HelicsFederate fed)

Release the memory associated with a federate.

void helicsFederateEnterInitializingMode(HelicsFederate fed, HelicsError *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.

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

void helicsFederateEnterInitializingModeAsync(HelicsFederate fed, HelicsError *err)

Non blocking alternative to helicsFederateEnterInitializingMode.

The function helicsFederateEnterInitializationModeFinalize must be called to finish the operation.

Parameters
  • fed – The federate to operate on.

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

HelicsBool helicsFederateIsAsyncOperationCompleted(HelicsFederate fed, HelicsError *err)

Check if the current Asynchronous operation has completed.

Parameters
  • fed – The federate to operate on.

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

Returns

HELICS_FALSE if not completed, HELICS_TRUE if completed.

void helicsFederateEnterInitializingModeComplete(HelicsFederate fed, HelicsError *err)

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

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

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

void helicsFederateEnterExecutingMode(HelicsFederate fed, HelicsError *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.

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

void helicsFederateEnterExecutingModeAsync(HelicsFederate fed, HelicsError *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.

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

void helicsFederateEnterExecutingModeComplete(HelicsFederate fed, HelicsError *err)

Complete the call to /ref helicsFederateEnterExecutingModeAsync.

Parameters
  • fed – The federate object to complete the call.

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

HelicsIterationResult helicsFederateEnterExecutingModeIterative(HelicsFederate fed, HelicsIterationRequest iterate, HelicsError *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.

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

Returns

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

void helicsFederateEnterExecutingModeIterativeAsync(HelicsFederate fed, HelicsIterationRequest iterate, HelicsError *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.

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

HelicsIterationResult helicsFederateEnterExecutingModeIterativeComplete(HelicsFederate fed, HelicsError *err)

Complete the asynchronous iterative call into ExecutionMode.

Parameters
  • fed – The federate to make the request of.

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

Returns

An iteration object containing the iteration time and iteration_status.

HelicsFederateState helicsFederateGetState(HelicsFederate fed, HelicsError *err)

Get the current state of a federate.

Parameters
  • fed – The federate 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.

Returns

State the resulting state if void return HELICS_OK.

HelicsCore helicsFederateGetCore(HelicsFederate fed, HelicsError *err)

Get the core object associated with a federate.

Parameters
  • fed – A federate object.

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

Returns

A core object, nullptr if invalid.

HelicsTime helicsFederateRequestTime(HelicsFederate fed, HelicsTime requestTime, HelicsError *err)

Request the next time for federate execution.

Parameters
  • fed – The federate to make the request of.

  • requestTime – The next requested time.

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

Returns

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

HelicsTime helicsFederateRequestTimeAdvance(HelicsFederate fed, HelicsTime timeDelta, HelicsError *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.

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

Returns

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

HelicsTime helicsFederateRequestNextStep(HelicsFederate fed, HelicsError *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.

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

Returns

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

HelicsTime helicsFederateRequestTimeIterative(HelicsFederate fed, HelicsTime requestTime, HelicsIterationRequest iterate, HelicsIterationResult *outIteration, HelicsError *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.

  • outIteration[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.

Returns

The granted time, will return HELICS_TIME_MAXTIME if the simulation has terminated along with the appropriate iteration result.

void helicsFederateRequestTimeAsync(HelicsFederate fed, HelicsTime requestTime, HelicsError *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.

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

HelicsTime helicsFederateRequestTimeComplete(HelicsFederate fed, HelicsError *err)

Complete an asynchronous requestTime call.

Parameters
  • fed – The federate to make the request of.

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

Returns

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

void helicsFederateRequestTimeIterativeAsync(HelicsFederate fed, HelicsTime requestTime, HelicsIterationRequest iterate, HelicsError *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.

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

HelicsTime helicsFederateRequestTimeIterativeComplete(HelicsFederate fed, HelicsIterationResult *outIterate, HelicsError *err)

Complete an iterative time request asynchronous call.

Parameters
  • fed – The federate to make the request of.

  • 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.

Returns

The granted time, will return HELICS_TIME_MAXTIME if the simulation has terminated.

const char *helicsFederateGetName(HelicsFederate fed)

Get the name of the federate.

Parameters

fed – The federate object to query.

Returns

A pointer to a string with the name.

void helicsFederateSetTimeProperty(HelicsFederate fed, int timeProperty, HelicsTime time, HelicsError *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.

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

void helicsFederateSetFlagOption(HelicsFederate fed, int flag, HelicsBool flagValue, HelicsError *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.

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

void helicsFederateSetSeparator(HelicsFederate fed, char separator, HelicsError *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.

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

void helicsFederateSetIntegerProperty(HelicsFederate fed, int intProperty, int propertyVal, HelicsError *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.

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

HelicsTime helicsFederateGetTimeProperty(HelicsFederate fed, int timeProperty, HelicsError *err)

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

Parameters
  • fed – The federate query.

  • timeProperty – The property 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.

HelicsBool helicsFederateGetFlagOption(HelicsFederate fed, int flag, HelicsError *err)

Get a flag value for a federate.

Parameters
  • fed – The federate to get the flag for.

  • flag – The flag to query.

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

Returns

The value of the flag.

int helicsFederateGetIntegerProperty(HelicsFederate fed, int intProperty, HelicsError *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.

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

Returns

The value of the property.

HelicsTime helicsFederateGetCurrentTime(HelicsFederate fed, HelicsError *err)

Get the current time of the federate.

Parameters
  • fed – The federate object to query.

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

Returns

The current time of the federate.

void helicsFederateSetGlobal(HelicsFederate fed, const char *valueName, const char *value, HelicsError *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.

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

void helicsFederateSetTag(HelicsFederate fed, const char *tagName, const char *value, HelicsError *err)

Set a federate tag value.

This overwrites any previous value for this tag.

Parameters
  • fed – The federate to set the tag for.

  • tagName – The name of the tag to set.

  • value – The value of the tag.

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

const char *helicsFederateGetTag(HelicsFederate fed, const char *tagName, HelicsError *err)

Get a federate tag value.

Parameters
  • fed – The federate to get the tag for.

  • tagName – The name of the tag to query.

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

void helicsFederateAddDependency(HelicsFederate fed, const char *fedName, HelicsError *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.

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

void helicsFederateSetLogFile(HelicsFederate fed, const char *logFile, HelicsError *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.

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

void helicsFederateLogErrorMessage(HelicsFederate fed, const char *logmessage, HelicsError *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.

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

void helicsFederateLogWarningMessage(HelicsFederate fed, const char *logmessage, HelicsError *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.

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

void helicsFederateLogInfoMessage(HelicsFederate fed, const char *logmessage, HelicsError *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.

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

void helicsFederateLogDebugMessage(HelicsFederate fed, const char *logmessage, HelicsError *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.

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

void helicsFederateLogLevelMessage(HelicsFederate fed, int loglevel, const char *logmessage, HelicsError *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.

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

void helicsFederateSendCommand(HelicsFederate fed, const char *target, const char *command, HelicsError *err)

Send a command to another helics object through a federate.

Parameters
  • fed – The federate to send the command through.

  • target – The name of the object to send the command to.

  • command – The command to send.

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

const char *helicsFederateGetCommand(HelicsFederate fed, HelicsError *err)

Get a command sent to the federate.

Parameters
  • fed – The federate to get the command for.

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

Returns

A string with the command for the federate, if the string is empty no command is available.

const char *helicsFederateGetCommandSource(HelicsFederate fed, HelicsError *err)

Get the source of the most recently retrieved command sent to the federate.

Parameters
  • fed – The federate to get the command for.

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

Returns

A string with the command for the federate, if the string is empty no command is available.

const char *helicsFederateWaitCommand(HelicsFederate fed, HelicsError *err)

Get a command sent to the federate. Blocks until a command is received.

Parameters
  • fed – The federate to get the command for.

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

Returns

A string with the command for the federate, if the string is empty no command is available.

void helicsFederateSetLoggingCallback(HelicsFederate fed, void (*logger)(int loglevel, const char *identifier, const char *message, void *userData), void *userdata, HelicsError *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.

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

void helicsFederateSetQueryCallback(HelicsFederate fed, void (*queryAnswer)(const char *query, int querySize, HelicsQueryBuffer buffer, void *userdata), void *userdata, HelicsError *err)

Set callback for queries executed against a federate.

There are many queries that HELICS understands directly, but it is occasionally useful to have a federate be able to respond to specific queries with answers specific to a federate.

Parameters
  • fed – The federate to set the callback for.

  • queryAnswer – A callback with signature const char *(const char *query, int querySize,int *answerSize, void *userdata); The function arguments are the query string requesting an answer along with its size, the string is not guaranteed to be null terminated answerSize is an outputParameter intended to filled out by the userCallback and should contain the length of the return string. The return pointer can be NULL if no answer is given and HELICS will generate the appropriate response.

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

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

ValueFederate

HelicsInput helicsFederateRegisterSubscription(HelicsFederate fed, const char *key, const char *units, HelicsError *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).

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

Returns

An object containing the subscription.

HelicsPublication helicsFederateRegisterPublication(HelicsFederate fed, const char *key, HelicsDataTypes type, const char *units, HelicsError *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 HelicsDataTypes for available options.

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

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

Returns

An object containing the publication.

HelicsPublication helicsFederateRegisterTypePublication(HelicsFederate fed, const char *key, const char *type, const char *units, HelicsError *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).

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

Returns

An object containing the publication.

HelicsPublication helicsFederateRegisterGlobalPublication(HelicsFederate fed, const char *key, HelicsDataTypes type, const char *units, HelicsError *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 HelicsDataTypes for available options.

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

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

Returns

An object containing the publication.

HelicsPublication helicsFederateRegisterGlobalTypePublication(HelicsFederate fed, const char *key, const char *type, const char *units, HelicsError *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).

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

Returns

An object containing the publication.

HelicsInput helicsFederateRegisterInput(HelicsFederate fed, const char *key, HelicsDataTypes type, const char *units, HelicsError *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 HelicsDataTypes for available options.

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

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

Returns

An object containing the input.

HelicsInput helicsFederateRegisterTypeInput(HelicsFederate fed, const char *key, const char *type, const char *units, HelicsError *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.

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

Returns

An object containing the publication.

HelicsPublication helicsFederateRegisterGlobalInput(HelicsFederate fed, const char *key, HelicsDataTypes type, const char *units, HelicsError *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 HelicsDataTypes for available options.

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

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

Returns

An object containing the publication.

HelicsPublication helicsFederateRegisterGlobalTypeInput(HelicsFederate fed, const char *key, const char *type, const char *units, HelicsError *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.

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

Returns

An object containing the publication.

HelicsPublication helicsFederateGetPublication(HelicsFederate fed, const char *key, HelicsError *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.

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

Returns

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

HelicsPublication helicsFederateGetPublicationByIndex(HelicsFederate fed, int index, HelicsError *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.

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

Returns

A HelicsPublication.

HelicsInput helicsFederateGetInput(HelicsFederate fed, const char *key, HelicsError *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.

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

Returns

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

HelicsInput helicsFederateGetInputByIndex(HelicsFederate fed, int index, HelicsError *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.

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

Returns

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

HelicsInput helicsFederateGetSubscription(HelicsFederate fed, const char *key, HelicsError *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.

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

Returns

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

void helicsFederateClearUpdates(HelicsFederate fed)

Clear all the update flags from a federates inputs.

Parameters

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

void helicsFederateRegisterFromPublicationJSON(HelicsFederate fed, const char *json, HelicsError *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.

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

void helicsFederatePublishJSON(HelicsFederate fed, const char *json, HelicsError *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.

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

int helicsFederateGetPublicationCount(HelicsFederate fed)

Get the number of publications in a federate.

Returns

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

int helicsFederateGetInputCount(HelicsFederate fed)

Get the number of subscriptions in a federate.

Returns

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

Publication

HelicsBool helicsPublicationIsValid(HelicsPublication pub)

Check if a publication is valid.

Parameters

pub – The publication to check.

Returns

HELICS_TRUE if the publication is a valid publication.

void helicsPublicationPublishBytes(HelicsPublication pub, const void *data, int inputDataLength, HelicsError *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.

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

void helicsPublicationPublishString(HelicsPublication pub, const char *str, HelicsError *err)

Publish a string.

Parameters
  • pub – The publication to publish for.

  • str – The string to publish.

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

void helicsPublicationPublishInteger(HelicsPublication pub, int64_t val, HelicsError *err)

Publish an integer value.

Parameters
  • pub – The publication to publish for.

  • val – The numerical value to publish.

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

void helicsPublicationPublishBoolean(HelicsPublication pub, HelicsBool val, HelicsError *err)

Publish a Boolean Value.

Parameters
  • pub – The publication to publish for.

  • val – The boolean value to publish.

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

void helicsPublicationPublishDouble(HelicsPublication pub, double val, HelicsError *err)

Publish a double floating point value.

Parameters
  • pub – The publication to publish for.

  • val – The numerical value to publish.

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

void helicsPublicationPublishTime(HelicsPublication pub, HelicsTime val, HelicsError *err)

Publish a time value.

Parameters
  • pub – The publication to publish for.

  • val – The numerical value to publish.

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

void helicsPublicationPublishChar(HelicsPublication pub, char val, HelicsError *err)

Publish a single character.

Parameters
  • pub – The publication to publish for.

  • val – The numerical value to publish.

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

void helicsPublicationPublishComplex(HelicsPublication pub, double real, double imag, HelicsError *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.

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

void helicsPublicationPublishVector(HelicsPublication pub, const double *vectorInput, int vectorLength, HelicsError *err)

Publish a vector of doubles.

Parameters
  • pub – The publication to publish for.

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

  • vectorLength – The number of points to publish.

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

void helicsPublicationPublishNamedPoint(HelicsPublication pub, const char *str, double val, HelicsError *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.

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

void helicsPublicationAddTarget(HelicsPublication pub, const char *target, HelicsError *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.

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

const char *helicsPublicationGetType(HelicsPublication pub)

Get the type of a publication.

Parameters

pub – The publication to query.

Returns

A void enumeration, HELICS_OK if everything worked.

const char *helicsPublicationGetName(HelicsPublication pub)

Get the name 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 const char with the publication name.

const char *helicsPublicationGetUnits(HelicsPublication pub)

Get the units of a publication.

Parameters

pub – The publication to query.

Returns

A void enumeration, HELICS_OK if everything worked.

const char *helicsPublicationGetInfo(HelicsPublication 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.

void helicsPublicationSetInfo(HelicsPublication pub, const char *info, HelicsError *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.

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

const char *helicsPublicationGetTag(HelicsPublication pub, const char *tagname)

Get the data in a specified tag of a publication.

Parameters
  • pub – The publication object to query.

  • tagname – The name of the tag to query.

Returns

A string with the tag data.

void helicsPublicationSetTag(HelicsPublication pub, const char *tagname, const char *tagvalue, HelicsError *err)

Set the data in a specific tag for a publication.

Parameters
  • pub – The publication object to set a tag for.

  • tagname – The name of the tag to set.

  • tagvalue – The string value to associate with a tag.

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

int helicsPublicationGetOption(HelicsPublication 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.

void helicsPublicationSetOption(HelicsPublication pub, int option, int val, HelicsError *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.

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

void helicsPublicationSetMinimumChange(HelicsPublication pub, double tolerance, HelicsError *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.

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

Input

HelicsBool helicsInputIsValid(HelicsInput ipt)

Check if an input is valid.

Parameters

ipt – The input to check.

Returns

HELICS_TRUE if the Input object represents a valid input.

void helicsInputAddTarget(HelicsInput ipt, const char *target, HelicsError *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.

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

int helicsInputGetByteCount(HelicsInput ipt)

Get the size of the raw value for subscription.

Returns

The size of the raw data/string in bytes.

void helicsInputGetBytes(HelicsInput ipt, void *data, int maxDataLength, int *actualSize, HelicsError *err)

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

Parameters
  • ipt – The input to get the data for.

  • 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.

int helicsInputGetStringSize(HelicsInput ipt)

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

Returns

The size of the string.

void helicsInputGetString(HelicsInput ipt, char *outputString, int maxStringLength, int *actualLength, HelicsError *err)

Get a string value from a subscription.

Parameters
  • ipt – The input to get the data for.

  • 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.

int64_t helicsInputGetInteger(HelicsInput ipt, HelicsError *err)

Get an integer value from a subscription.

Parameters
  • ipt – The input to get the data for.

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

Returns

An int64_t value with the current value of the input.

HelicsBool helicsInputGetBoolean(HelicsInput ipt, HelicsError *err)

Get a boolean value from a subscription.

Parameters
  • ipt – The input to get the data for.

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

Returns

A boolean value of current input value.

double helicsInputGetDouble(HelicsInput ipt, HelicsError *err)

Get a double value from a subscription.

Parameters
  • ipt – The input to get the data for.

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

Returns

The double value of the input.

HelicsTime helicsInputGetTime(HelicsInput ipt, HelicsError *err)

Get a time value from a subscription.

Parameters
  • ipt – The input to get the data for.

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

Returns

The resulting time value.

char helicsInputGetChar(HelicsInput ipt, HelicsError *err)

Get a single character value from an input.

Parameters
  • ipt – The input to get the data for.

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

Returns

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

HelicsComplex helicsInputGetComplexObject(HelicsInput ipt, HelicsError *err)

Get a complex object from an input object.

Parameters
  • ipt – The input to get the data for.

  • 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.

Returns

A HelicsComplex structure with the value.

void helicsInputGetComplex(HelicsInput ipt, double *real, double *imag, HelicsError *err)

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

Parameters
  • ipt – The input to get the data for.

  • 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.

int helicsInputGetVectorSize(HelicsInput 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.

void helicsInputGetVector(HelicsInput ipt, double data[], int maxLength, int *actualSize, HelicsError *err)

Get a vector from a subscription.

Parameters
  • ipt – The input to get the result for.

  • 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.

void helicsInputGetNamedPoint(HelicsInput ipt, char *outputString, int maxStringLength, int *actualLength, double *val, HelicsError *err)

Get a named point from a subscription.

Parameters
  • ipt – The input to get the result for.

  • 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.

void helicsInputSetDefaultBytes(HelicsInput ipt, const void *data, int inputDataLength, HelicsError *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.

  • 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.

void helicsInputSetDefaultString(HelicsInput ipt, const char *str, HelicsError *err)

Set the default as a string.

Parameters
  • ipt – The input to set the default for.

  • str – A pointer to the default string.

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

void helicsInputSetDefaultInteger(HelicsInput ipt, int64_t val, HelicsError *err)

Set the default as an integer.

Parameters
  • ipt – The input to set the default for.

  • val – The default integer.

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

void helicsInputSetDefaultBoolean(HelicsInput ipt, HelicsBool val, HelicsError *err)

Set the default as a boolean.

Parameters
  • ipt – The input to set the default for.

  • val – The default boolean value.

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

void helicsInputSetDefaultTime(HelicsInput ipt, HelicsTime val, HelicsError *err)

Set the default as a time.

Parameters
  • ipt – The input to set the default for.

  • val – The default time value.

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

void helicsInputSetDefaultChar(HelicsInput ipt, char val, HelicsError *err)

Set the default as a char.

Parameters
  • ipt – The input to set the default for.

  • val – The default char value.

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

void helicsInputSetDefaultDouble(HelicsInput ipt, double val, HelicsError *err)

Set the default as a double.

Parameters
  • ipt – The input to set the default for.

  • val – The default double value.

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

void helicsInputSetDefaultComplex(HelicsInput ipt, double real, double imag, HelicsError *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.

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

void helicsInputSetDefaultVector(HelicsInput ipt, const double *vectorInput, int vectorLength, HelicsError *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 doubles in the vector.

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

void helicsInputSetDefaultNamedPoint(HelicsInput ipt, const char *str, double val, HelicsError *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.

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

const char *helicsInputGetType(HelicsInput ipt)

Get the type of an input.

Parameters

ipt – The input to query.

Returns

A void enumeration, HELICS_OK if everything worked.

const char *helicsInputGetPublicationType(HelicsInput 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.

const char *helicsInputGetName(HelicsInput ipt)

Get the key of an input.

Parameters

ipt – The input to query.

Returns

A const char with the input name.

const char *helicsSubscriptionGetTarget(HelicsInput ipt)

Get the target of a subscription.

Returns

A const char with the subscription target.

const char *helicsInputGetUnits(HelicsInput ipt)

Get the units of an input.

Parameters

ipt – The input to query.

Returns

A void enumeration, HELICS_OK if everything worked.

const char *helicsInputGetInjectionUnits(HelicsInput 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.

const char *helicsInputGetExtractionUnits(HelicsInput 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(HelicsInput 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.

void helicsInputSetInfo(HelicsInput inp, const char *info, HelicsError *err)

Set the data in the info field for an input.

Parameters
  • inp – The input to query.

  • info – The string to set.

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

const char *helicsInputGetTag(HelicsInput inp, const char *tagname)

Get the data in a specified tag of an input.

Parameters
  • inp – The input object to query.

  • tagname – The name of the tag to get the value for.

Returns

A string with the tag data.

void helicsInputSetTag(HelicsInput inp, const char *tagname, const char *tagvalue, HelicsError *err)

Set the data in a specific tag for an input.

Parameters
  • inp – The input object to query.

  • tagname – The string to set.

  • tagvalue – The string value to associate with a tag.

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

int helicsInputGetOption(HelicsInput 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.

void helicsInputSetOption(HelicsInput inp, int option, int value, HelicsError *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.

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

void helicsInputSetMinimumChange(HelicsInput inp, double tolerance, HelicsError *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.

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

HelicsBool helicsInputIsUpdated(HelicsInput ipt)

Check if a particular subscription was updated.

Returns

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

HelicsTime helicsInputLastUpdateTime(HelicsInput ipt)

Get the last time a subscription was updated.

void helicsInputClearUpdate(HelicsInput ipt)

Clear the updated flag from an input.

MessageFederate

HelicsEndpoint helicsFederateRegisterEndpoint(HelicsFederate fed, const char *name, const char *type, HelicsError *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).

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

Returns

An object containing the endpoint.

    nullptr on failure.

HelicsEndpoint helicsFederateRegisterGlobalEndpoint(HelicsFederate fed, const char *name, const char *type, HelicsError *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).

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

Returns

An object containing the endpoint.

    nullptr on failure.

HelicsEndpoint helicsFederateRegisterTargetedEndpoint(HelicsFederate fed, const char *name, const char *type, HelicsError *err)

Create a targeted endpoint. Targeted endpoints have specific destinations predefined and do not allow sending messages to other endpoints

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).

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

Returns

An object containing the endpoint.

    nullptr on failure.

HelicsEndpoint helicsFederateRegisterGlobalTargetedEndpoint(HelicsFederate fed, const char *name, const char *type, HelicsError *err)

Create a global targeted endpoint, Targeted endpoints have specific destinations predefined and do not allow sending messages to other endpoints

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).

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

Returns

An object containing the endpoint.

    nullptr on failure.

HelicsEndpoint helicsFederateGetEndpoint(HelicsFederate fed, const char *name, HelicsError *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.

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

Returns

A HelicsEndpoint object.

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

HelicsEndpoint helicsFederateGetEndpointByIndex(HelicsFederate fed, int index, HelicsError *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.

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

Returns

A HelicsEndpoint.

    It will be NULL if given an invalid index.

HelicsBool helicsFederateHasMessage(HelicsFederate 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.

int helicsFederatePendingMessageCount(HelicsFederate fed)

Returns the number of pending receives for the specified destination endpoint.

Parameters

fed – The federate to get the number of waiting messages from.

HelicsMessage helicsFederateGetMessage(HelicsFederate 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 HelicsMessage which references the data in the message.

HelicsMessage helicsFederateCreateMessage(HelicsFederate fed, HelicsError *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

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

Returns

A HelicsMessage containing the message data.

void helicsFederateClearMessages(HelicsFederate fed)

Clear all stored messages from a federate.

This clears messages retrieved through helicsEndpointGetMessage or helicsFederateGetMessage

Parameters

fed – The federate to clear the message for.

int helicsFederateGetEndpointCount(HelicsFederate 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.

Endpoint

HelicsBool helicsEndpointIsValid(HelicsEndpoint 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.

void helicsEndpointSetDefaultDestination(HelicsEndpoint endpoint, const char *dst, HelicsError *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.

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

const char *helicsEndpointGetDefaultDestination(HelicsEndpoint endpoint)

Get the default destination for an endpoint.

Parameters

endpoint – The endpoint to set the destination for.

Returns

A string with the default destination.

void helicsEndpointSendBytes(HelicsEndpoint endpoint, const void *data, int inputDataLength, HelicsError *err)

Send a message to the targeted destination.

Parameters
  • endpoint – The endpoint to send the data from.

  • data – The data to send.

  • inputDataLength – The length of the data to send.

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

void helicsEndpointSendBytesTo(HelicsEndpoint endpoint, const void *data, int inputDataLength, const char *dst, HelicsError *err)

Send a message to the specified destination.

Parameters
  • endpoint – The endpoint to send the data from.

  • data – The data to send.

  • inputDataLength – The length of the data to send.

  • dst – The target destination.

            nullptr to use the default destination.
    

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

void helicsEndpointSendBytesToAt(HelicsEndpoint endpoint, const void *data, int inputDataLength, const char *dst, HelicsTime time, HelicsError *err)

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

Parameters
  • endpoint – The endpoint to send the data from.

  • data – The data to send.

  • inputDataLength – The length of the data to send.

  • dst – The target destination.

            nullptr to use the default destination.
    

  • time – The time the message should be sent.

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

void helicsEndpointSendBytesAt(HelicsEndpoint endpoint, const void *data, int inputDataLength, HelicsTime time, HelicsError *err)

Send a message at a specific time to the targeted destinations

Parameters
  • endpoint – The endpoint to send the data from.

  • data – The data to send.

  • inputDataLength – The length of the data to send.

  • time – The time the message should be sent.

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

void helicsEndpointSendMessage(HelicsEndpoint endpoint, HelicsMessage message, HelicsError *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.

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

void helicsEndpointSendMessageZeroCopy(HelicsEndpoint endpoint, HelicsMessage message, HelicsError *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.

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

void helicsEndpointSubscribe(HelicsEndpoint endpoint, const char *key, HelicsError *err)

Subscribe an endpoint to a publication.

Parameters
  • endpoint – The endpoint to use.

  • key – The name of the publication.

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

HelicsBool helicsEndpointHasMessage(HelicsEndpoint 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.

int helicsEndpointPendingMessageCount(HelicsEndpoint endpoint)

Returns the number of pending receives for all endpoints of a particular federate.

Parameters

endpoint – The endpoint to query.

HelicsMessage helicsEndpointGetMessage(HelicsEndpoint endpoint)

Receive a packet from a particular endpoint.

Parameters

endpoint[in] The identifier for the endpoint.

Returns

A message object.

HelicsMessage helicsEndpointCreateMessage(HelicsEndpoint endpoint, HelicsError *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.

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

Returns

A new HelicsMessage.

const char *helicsEndpointGetType(HelicsEndpoint endpoint)

Get the type specified for an endpoint.

Parameters

endpoint – The endpoint object in question.

Returns

The defined type of the endpoint.

const char *helicsEndpointGetName(HelicsEndpoint endpoint)

Get the name of an endpoint.

Parameters

endpoint – The endpoint object in question.

Returns

The name of the endpoint.

const char *helicsEndpointGetInfo(HelicsEndpoint end)

Get the local information field of an endpoint.

Parameters

end – The endpoint to query.

Returns

A string with the info field string.

void helicsEndpointSetInfo(HelicsEndpoint endpoint, const char *info, HelicsError *err)

Set the data in the interface information field for an endpoint.

Parameters
  • endpoint – The endpoint to set the information for

  • info – The string to store in the field

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

const char *helicsEndpointGetTag(HelicsEndpoint endpoint, const char *tagname)

Get the data in a specified tag of an endpoint

Parameters
  • endpoint – The endpoint to query.

  • tagname – The name of the tag to query.

Returns

A string with the tag data.

void helicsEndpointSetTag(HelicsEndpoint endpoint, const char *tagname, const char *tagvalue, HelicsError *err)

Set the data in a specific tag for an endpoint.

Parameters
  • endpoint – The endpoint to query.

  • tagname – The string to set.

  • tagvalue – The string value to associate with a tag.

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

void helicsEndpointSetOption(HelicsEndpoint endpoint, int option, int value, HelicsError *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.

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

int helicsEndpointGetOption(HelicsEndpoint 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

void helicsEndpointAddSourceTarget(HelicsEndpoint endpoint, const char *targetEndpoint, HelicsError *err)

add a source target to an endpoint, Specifying an endpoint to receive undirected messages from

Parameters
  • endpoint – The endpoint to modify.

  • targetEndpoint – the endpoint to get messages from

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

void helicsEndpointAddDestinationTarget(HelicsEndpoint endpoint, const char *targetEndpoint, HelicsError *err)

add a destination target to an endpoint, Specifying an endpoint to send undirected messages to

Parameters
  • endpoint – The endpoint to modify.

  • targetEndpoint – the name of the endpoint to send messages to

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

void helicsEndpointRemoveTarget(HelicsEndpoint endpoint, const char *targetEndpoint, HelicsError *err)

remove an endpoint from being targeted

Parameters
  • endpoint – The endpoint to modify.

  • targetEndpoint – the name of the endpoint to send messages to

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

void helicsEndpointAddSourceFilter(HelicsEndpoint endpoint, const char *filterName, HelicsError *err)

add a source Filter to an endpoint

Parameters
  • endpoint – The endpoint to modify.

  • filterName – the name of the filter to add

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

void helicsEndpointAddDestinationFilter(HelicsEndpoint endpoint, const char *filterName, HelicsError *err)

add a destination filter to an endpoint

Parameters
  • endpoint – The endpoint to modify.

  • filterName – The name of the filter to add.

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

Message

const char *helicsMessageGetSource(HelicsMessage message)

Get the source endpoint of a message.

Parameters

message – The message object in question.

Returns

A string with the source endpoint.

const char *helicsMessageGetDestination(HelicsMessage message)

Get the destination endpoint of a message.

Parameters

message – The message object in question.

Returns

A string with the destination endpoint.

const char *helicsMessageGetOriginalSource(HelicsMessage 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.

const char *helicsMessageGetOriginalDestination(HelicsMessage 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.

HelicsTime helicsMessageGetTime(HelicsMessage message)

Get the helics time associated with a message.

Parameters

message – The message object in question.

Returns

The time associated with a message.

const char *helicsMessageGetString(HelicsMessage 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.

int helicsMessageGetMessageID(HelicsMessage message)

Get the messageID of a message.

Parameters

message – The message object in question.

Returns

The messageID.

HelicsBool helicsMessageGetFlagOption(HelicsMessage 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.

int helicsMessageGetByteCount(HelicsMessage message)

Get the size of the data payload in bytes.

Parameters

message – The message object in question.

Returns

The size of the data payload.

void helicsMessageGetBytes(HelicsMessage message, void *data, int maxMessageLength, int *actualSize, HelicsError *err)

Get the raw data for a message object.

Parameters
  • message – A message object to get the data for.

  • 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.

HelicsBool helicsMessageIsValid(HelicsMessage 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 helicsMessageSetSource(HelicsMessage message, const char *src, HelicsError *err)

Set the source of a message.

Parameters
  • message – The message object in question.

  • src – A string containing the source.

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

void helicsMessageSetDestination(HelicsMessage message, const char *dst, HelicsError *err)

Set the destination of a message.

Parameters
  • message – The message object in question.

  • dst – A string containing the new destination.

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

void helicsMessageSetOriginalSource(HelicsMessage message, const char *src, HelicsError *err)

Set the original source of a message.

Parameters
  • message – The message object in question.

  • src – A string containing the new original source.

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

void helicsMessageSetOriginalDestination(HelicsMessage message, const char *dst, HelicsError *err)

Set the original destination of a message.

Parameters
  • message – The message object in question.

  • dst – A string containing the new original source.

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

void helicsMessageSetTime(HelicsMessage message, HelicsTime time, HelicsError *err)

Set the delivery time for a message.

Parameters
  • message – The message object in question.

  • time – The time the message should be delivered.

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

void helicsMessageResize(HelicsMessage message, int newSize, HelicsError *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.

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

void helicsMessageReserve(HelicsMessage message, int reserveSize, HelicsError *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.

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

void helicsMessageSetMessageID(HelicsMessage message, int32_t messageID, HelicsError *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.

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

void helicsMessageClearFlags(HelicsMessage message)

Clear the flags of a message.

Parameters

message – The message object in question

void helicsMessageSetFlagOption(HelicsMessage message, int flag, HelicsBool flagValue, HelicsError *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.

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

void helicsMessageSetString(HelicsMessage message, const char *str, HelicsError *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.

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

void helicsMessageSetData(HelicsMessage message, const void *data, int inputDataLength, HelicsError *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.

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

void helicsMessageAppendData(HelicsMessage message, const void *data, int inputDataLength, HelicsError *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.

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

void helicsMessageCopy(HelicsMessage src_message, HelicsMessage dst_message, HelicsError *err)

Copy a message object.

Parameters
  • src_message – The message object to copy from.

  • dst_message – The message object to copy to.

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

HelicsMessage helicsMessageClone(HelicsMessage message, HelicsError *err)

Clone a message object.

Parameters
  • message – The message object to copy from.

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

void helicsMessageFree(HelicsMessage 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.

void helicsMessageClear(HelicsMessage message, HelicsError *err)

Reset a message to empty state

The message after this function will be empty, with no source or destination

Parameters
  • message – The message object to copy from.

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

FilterFederate

HelicsFilter helicsFederateRegisterFilter(HelicsFederate fed, HelicsFilterTypes type, const char *name, HelicsError *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 HelicsFilterTypes.

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

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

Returns

A HelicsFilter object.

HelicsFilter helicsFederateRegisterGlobalFilter(HelicsFederate fed, HelicsFilterTypes type, const char *name, HelicsError *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 HelicsFilterTypes.

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

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

Returns

A HelicsFilter object.

HelicsFilter helicsFederateRegisterCloningFilter(HelicsFederate fed, const char *name, HelicsError *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).

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

Returns

A HelicsFilter object.

HelicsFilter helicsFederateRegisterGlobalCloningFilter(HelicsFederate fed, const char *name, HelicsError *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).

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

Returns

A HelicsFilter object.

int helicsFederateGetFilterCount(HelicsFederate 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.

HelicsFilter helicsFederateGetFilter(HelicsFederate fed, const char *name, HelicsError *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.

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

Returns

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

HelicsFilter helicsFederateGetFilterByIndex(HelicsFederate fed, int index, HelicsError *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.

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

Returns

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

Filter

void helicsFilterSetCustomCallback(HelicsFilter filter, void (*filtCall)(HelicsMessage message, void *userData), void *userdata, HelicsError *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.

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

HelicsBool helicsFilterIsValid(HelicsFilter 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.

const char *helicsFilterGetName(HelicsFilter 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.

void helicsFilterSet(HelicsFilter filt, const char *prop, double val, HelicsError *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.

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

void helicsFilterSetString(HelicsFilter filt, const char *prop, const char *val, HelicsError *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.

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

void helicsFilterAddDestinationTarget(HelicsFilter filt, const char *dst, HelicsError *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.

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

void helicsFilterAddSourceTarget(HelicsFilter filt, const char *source, HelicsError *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.

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

void helicsFilterAddDeliveryEndpoint(HelicsFilter filt, const char *deliveryEndpoint, HelicsError *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.

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

void helicsFilterRemoveTarget(HelicsFilter filt, const char *target, HelicsError *err)

Remove a destination target from a filter.

Parameters
  • filt – The given filter.

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

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

void helicsFilterRemoveDeliveryEndpoint(HelicsFilter filt, const char *deliveryEndpoint, HelicsError *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.

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

const char *helicsFilterGetInfo(HelicsFilter filt)

Get the data in the info field of a filter.

Parameters

filt – The given filter.

Returns

A string with the info field string.

void helicsFilterSetInfo(HelicsFilter filt, const char *info, HelicsError *err)

Set the data in the info field for a filter.

Parameters
  • filt – The given filter.

  • info – The string to set.

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

const char *helicsFilterGetTag(HelicsFilter filt, const char *tagname)

Get the data in a specified tag of a filter.

Parameters
  • filt – The filter to query.

  • tagname – The name of the tag to query.

Returns

A string with the tag data.

void helicsFilterSetTag(HelicsFilter filt, const char *tagname, const char *tagvalue, HelicsError *err)

Set the data in a specific tag for a filter.

Parameters
  • filt – The filter object to set the tag for.

  • tagname – The string to set.

  • tagvalue – the string value to associate with a tag.

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

void helicsFilterSetOption(HelicsFilter filt, int option, int value, HelicsError *err)

Set an option value 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.

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

int helicsFilterGetOption(HelicsFilter 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.

Query

const char *helicsQueryExecute(HelicsQuery query, HelicsFederate fed, HelicsError *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.

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

Returns

A pointer to a string. The string will remain valid until the query is freed or executed again.

    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.

const char *helicsQueryCoreExecute(HelicsQuery query, HelicsCore core, HelicsError *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.

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

Returns

A pointer to a string. The string will remain valid until the query is freed or executed again.

    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.

const char *helicsQueryBrokerExecute(HelicsQuery query, HelicsBroker broker, HelicsError *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.

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

Returns

A pointer to a string. The string will remain valid until the query is freed or executed again.

    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

void helicsQueryExecuteAsync(HelicsQuery query, HelicsFederate fed, HelicsError *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.

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

const char *helicsQueryExecuteComplete(HelicsQuery query, HelicsError *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.

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

Returns

A pointer to a string. The string will remain valid until the query is freed or executed again.

    The return will be nullptr if query is an invalid object

HelicsBool helicsQueryIsCompleted(HelicsQuery 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

void helicsQuerySetTarget(HelicsQuery query, const char *target, HelicsError *err)

Update the target of a query.

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.

void helicsQuerySetQueryString(HelicsQuery query, const char *queryString, HelicsError *err)

Update the queryString of a query.

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

  • queryString – the new queryString

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

void helicsQuerySetOrdering(HelicsQuery query, int32_t mode, HelicsError *err)

Update the ordering mode of the query, fast runs on priority channels, ordered goes on normal channels but goes in sequence

Parameters
  • query – The query object to change the order for.

  • mode – 0 for fast, 1 for ordered

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

void helicsQueryFree(HelicsQuery query)

Free the memory associated with a query object.

void helicsQueryBufferFill(HelicsQueryBuffer buffer, const char *str, int strSize, HelicsError *err)

Set the data for a query callback.

There are many queries that HELICS understands directly, but it is occasionally useful to have a federate be able to respond to specific queries with answers specific to a federate.

Parameters
  • buffer – The buffer received in a helicsQueryCallback.

  • str – Pointer to the data to fill the buffer with.

  • strSize – The size of the string.

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