C API Reference¶
Enum¶
-
enumerator helics_core_type_default¶
a default core type that will default to something available
-
enumerator helics_core_type_http¶
a core type using http for communication
-
enumerator helics_core_type_inproc¶
an in process core type for handling communications in shared memory it is pretty similar to the test core but stripped from the “test” components
-
enumerator helics_core_type_interprocess¶
interprocess uses memory mapped files to transfer data (for use when all federates are on the same machine
-
enumerator helics_core_type_ipc¶
interprocess uses memory mapped files to transfer data (for use when all federates are on the same machine ipc is the same as /ref helics_core_type_interprocess
-
enumerator helics_core_type_mpi¶
use MPI for operation on a parallel cluster
-
enumerator helics_core_type_nng¶
for using the nanomsg communications
-
enumerator helics_core_type_null¶
an explicit core type that is recognized but explicitly doesn’t exist, for testing and a few other assorted reasons
-
enumerator helics_core_type_tcp¶
use a generic TCP protocol message stream to send messages
-
enumerator helics_core_type_tcp_ss¶
a single socket version of the TCP core for more easily handling firewalls
-
enumerator helics_core_type_test¶
use the Test core if all federates are in the same process
-
enumerator helics_core_type_udp¶
use UDP packets to send the data
-
enumerator helics_core_type_websocket¶
a core using websockets for communication
-
enumerator helics_core_type_zmq¶
use the Zero MQ networking protocol
-
enumerator helics_core_type_zmq_test¶
single socket version of ZMQ core usually for high fed count on the same system
-
enumerator helics_data_type_any¶
open type that can be anything
-
enumerator helics_data_type_boolean¶
a boolean data type
-
enumerator helics_data_type_complex¶
a pair of doubles representing a complex number
-
enumerator helics_data_type_complex_vector¶
a complex vector object
-
enumerator helics_data_type_double¶
a double precision floating point number
-
enumerator helics_data_type_int¶
a 64 bit integer
-
enumerator helics_data_type_named_point¶
a named point consisting of a string and a double
-
enumerator helics_data_type_raw¶
raw data type
-
enumerator helics_data_type_string¶
a sequence of characters
-
enumerator helics_data_type_time¶
time data type
-
enumerator helics_data_type_vector¶
an array of doubles
-
enumerator helics_error_connection_failure¶
the operation to connect has failed
-
enumerator helics_error_discard¶
the input was discarded and not used for some reason
-
enumerator helics_error_execution_failure¶
the function execution has failed
-
enumerator helics_error_external_type¶
an unknown non-helics error was produced
-
enumerator helics_error_fatal¶
global fatal error for federation
-
enumerator helics_error_insufficient_space¶
insufficient space is available to store requested data
-
enumerator helics_error_invalid_argument¶
the parameter passed was invalid and unable to be used
-
enumerator helics_error_invalid_function_call¶
the call made was invalid in the present state of the calling object
-
enumerator helics_error_invalid_object¶
indicator that the object used was not a valid object
-
enumerator helics_error_invalid_state_transition¶
error issued when an invalid state transition occurred
-
enumerator helics_error_other¶
the function produced a helics error of some other type
-
enumerator helics_error_registration_failure¶
registration has failed
-
enumerator helics_error_system_failure¶
the federate has terminated unexpectedly and the call cannot be completed
-
enumerator helics_filter_type_clone¶
a filter type that duplicates a message and sends the copy to a different destination
-
enumerator helics_filter_type_custom¶
a custom filter type that executes a user defined callback
-
enumerator helics_filter_type_delay¶
a filter type that executes a fixed delay on a message
-
enumerator helics_filter_type_firewall¶
a customizable filter type that can perform different actions on a message based on firewall like rules
-
enumerator helics_filter_type_random_delay¶
a filter type that executes a random delay on the messages
-
enumerator helics_filter_type_random_drop¶
a filter type that randomly drops messages
-
enumerator helics_filter_type_reroute¶
a filter type that reroutes a message to a different destination than originally specified
-
enumerator helics_flag_delay_init_entry¶
used to delay a core from entering initialization mode even if it would otherwise be ready
-
enumerator helics_flag_enable_init_entry¶
used to clear the HELICS_DELAY_INIT_ENTRY flag in cores
-
enumerator helics_flag_forward_compute¶
flag indicating that a federate performs forward computation and does internal rollback
-
enumerator helics_flag_ignore_time_mismatch_warnings¶
used to not display warnings on mismatched requested times
-
enumerator helics_flag_interruptible¶
flag indicating that a federate can be interrupted
-
enumerator helics_flag_observer¶
flag indicating that a federate is observe only
-
enumerator helics_flag_only_transmit_on_change¶
flag indicating a federate/interface should only transmit values if they have changed(binary equivalence)
-
enumerator helics_flag_only_update_on_change¶
flag indicating a federate/interface should only trigger an update if a value has changed (binary equivalence)
-
enumerator helics_flag_realtime¶
flag indicating that a federate needs to run in real time
-
enumerator helics_flag_restrictive_time_policy¶
flag indicating a federate should operate on a restrictive time policy, which disallows some 2nd order time evaluation and can be useful for certain types of dependency cycles and update patterns, but generally shouldn’t be used as it can lead to some very slow update conditions
-
enumerator helics_flag_rollback¶
flag indicating that a federate has rollback capability
-
enumerator helics_flag_single_thread_federate¶
flag indicating that the federate will only interact on a single thread
-
enumerator helics_flag_slow_responding¶
flag specifying that a federate, core, or broker may be slow to respond to pings If the federate goes offline there is no good way to detect it so use with caution
-
enumerator helics_flag_source_only¶
flag indicating that a federate/interface is a signal generator only
-
enumerator helics_flag_terminate_on_error¶
specify that a federate error should terminate the federation
-
enumerator helics_flag_uninterruptible¶
flag indicating that a federate can only return requested times
-
enumerator helics_flag_wait_for_current_time_update¶
flag indicating a federate should only grant time if all other federates have already passed the requested time
-
enumerator helics_handle_option_buffer_data¶
specify that the last data should be buffered and sent on subscriptions after init
-
enumerator helics_handle_option_connection_optional¶
specify that a connection is NOT required for an interface and will only be made if available no warning will be issues if not available
-
enumerator helics_handle_option_connection_required¶
specify that a connection is required for an interface and will generate an error if not available
-
enumerator helics_handle_option_ignore_interrupts¶
specify that an interface does not participate in determining time interrupts
-
enumerator helics_handle_option_ignore_unit_mismatch¶
specify that the mismatching units should be ignored
-
enumerator helics_handle_option_multiple_connections_allowed¶
specify that multiple connections are allowed for an interface
-
enumerator helics_handle_option_only_transmit_on_change¶
specify that an interface will only transmit on change(only applicable to publications)
-
enumerator helics_handle_option_only_update_on_change¶
specify that an interface will only update if the value has actually changed
-
enumerator helics_handle_option_single_connection_only¶
specify that only a single connection is allowed for an interface
-
enumerator helics_handle_option_strict_type_checking¶
specify that the types should be checked strictly for pub/sub and filters
-
enumerator helics_iteration_request_force_iteration¶
force iteration return when able
-
enumerator helics_iteration_request_iterate_if_needed¶
only return an iteration if necessary
-
enumerator helics_iteration_request_no_iteration¶
no iteration is requested
-
enumerator helics_iteration_result_error¶
there was an error
-
enumerator helics_iteration_result_halted¶
the federation has halted
-
enumerator helics_iteration_result_iterating¶
the federate is iterating at current time
-
enumerator helics_iteration_result_next_step¶
the iterations have progressed to the next time
-
enumerator helics_log_level_connections¶
summary+ notices about federate and broker connections +messages about network connections
-
enumerator helics_log_level_data¶
timing+ data transfer notices
-
enumerator helics_log_level_error¶
only print error level indicators
-
enumerator helics_log_level_interfaces¶
connections+ interface definitions
-
enumerator helics_log_level_no_print¶
don’t print anything except a few catastrophic errors
-
enumerator helics_log_level_summary¶
warning errors and summary level information
-
enumerator helics_log_level_timing¶
interfaces + timing message
-
enumerator helics_log_level_trace¶
all internal messages
-
enumerator helics_log_level_warning¶
only print warnings and errors
-
enumerator helics_ok¶
the function executed successfully
-
enumerator helics_property_int_console_log_level¶
integer property controlling the log level for file logging in a federate see helics_log_levels
-
enumerator helics_property_int_file_log_level¶
integer property controlling the log level for file logging in a federate see helics_log_levels
-
enumerator helics_property_int_log_level¶
integer property controlling the log level in a federate see helics_log_levels
-
enumerator helics_property_int_max_iterations¶
integer property controlling the maximum number of iterations in a federate
-
enumerator helics_property_time_delta¶
the property controlling the minimum time delta for a federate
-
enumerator helics_property_time_input_delay¶
the property controlling input delay for a federate
-
enumerator helics_property_time_offset¶
the property controlling time offset for the period of federate
-
enumerator helics_property_time_output_delay¶
the property controlling output delay for a federate
-
enumerator helics_property_time_period¶
the property controlling the period for a federate
-
enumerator helics_property_time_rt_lag¶
the property controlling real time lag for a federate the max time a federate can lag real time
-
enumerator helics_property_time_rt_lead¶
the property controlling real time lead for a federate the max time a federate can be ahead of real time
-
enumerator helics_property_time_rt_tolerance¶
the property controlling real time tolerance for a federate sets both rt_lag and rt_lead
-
enumerator helics_state_error¶
error state no core communication is possible but values can be retrieved
-
enumerator helics_state_execution¶
entered after the enterExectuationState call has returned
-
enumerator helics_state_finalize¶
the federate has finished executing normally final values may be retrieved
-
enumerator helics_state_initialization¶
entered after the enterInitializingMode call has returned
-
enumerator helics_state_pending_exec¶
state pending EnterExecution State
-
enumerator helics_state_pending_finalize¶
state that the federate is pending a finalize request
-
enumerator helics_state_pending_init¶
indicator that the federate is pending entry to initialization state
-
enumerator helics_state_pending_iterative_time¶
state that the federate is pending an iterative time request
-
enumerator helics_state_pending_time¶
state that the federate is pending a timeRequest
-
enumerator helics_state_startup¶
when created the federate is in startup state
-
enumerator helics_warning¶
the function issued a warning of some kind
Functions¶
Broker
Core
Endpoint
FederateInfo
Federate
Filter
Input
Message
Publication
Query
Broker¶
-
void helicsBrokerAddDestinationFilterToEndpoint(helics_broker broker, const char *filter, const char *endpoint, helics_error *err)¶
Link a named filter to a destination endpoint.
- Parameters
broker – The broker to generate the connection from.
filter – The name of the filter (cannot be NULL).
endpoint – The name of the endpoint to filter the data going to (cannot be NULL). @forcpponly
err – [inout] A helics_error object, can be NULL if the errors are to be ignored. @endforcpponly
-
void helicsBrokerAddSourceFilterToEndpoint(helics_broker broker, const char *filter, const char *endpoint, helics_error *err)¶
Link a named filter to a source endpoint.
- Parameters
broker – The broker to generate the connection from.
filter – The name of the filter (cannot be NULL).
endpoint – The name of the endpoint to filter the data from (cannot be NULL). @forcpponly
err – [inout] A helics_error object, can be NULL if the errors are to be ignored. @endforcpponly
-
helics_broker helicsBrokerClone(helics_broker broker, helics_error *err)¶
Create a new reference to an existing broker.
This will create a new broker object that references the existing broker it must be freed as well.
- Parameters
broker – An existing helics_broker. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
A new reference to the same broker.
-
void helicsBrokerDataLink(helics_broker broker, const char *source, const char *target, helics_error *err)¶
Link a named publication and named input using a broker.
- Parameters
broker – The broker to generate the connection from.
source – The name of the publication (cannot be NULL).
target – The name of the target to send the publication data (cannot be NULL). @forcpponly
err – [inout] A helics_error object, can be NULL if the errors are to be ignored. @endforcpponly
-
void helicsBrokerDestroy(helics_broker broker)¶
Disconnect and free a broker.
-
void helicsBrokerDisconnect(helics_broker broker, helics_error *err)¶
Disconnect a broker.
- Parameters
broker – The broker to disconnect. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsBrokerFree(helics_broker broker)¶
Release the memory associated with a broker.
-
const char *helicsBrokerGetAddress(helics_broker broker)¶
Get the network address associated with a broker.
- Parameters
broker – The broker to query.
- Returns
A string with the network address of the broker.
-
const char *helicsBrokerGetIdentifier(helics_broker broker)¶
Get an identifier for the broker.
- Parameters
broker – The broker to query.
- Returns
A string containing the identifier for the broker.
-
helics_bool helicsBrokerIsConnected(helics_broker broker)¶
Check if a broker is connected.
A connected broker implies it is attached to cores or cores could reach out to communicate.
- Returns
helics_false if not connected.
-
helics_bool helicsBrokerIsValid(helics_broker broker)¶
Check if a broker object is a valid object.
- Parameters
broker – The helics_broker object to test.
-
void helicsBrokerMakeConnections(helics_broker broker, const char *file, helics_error *err)¶
Load a file containing connection information.
- Parameters
broker – The broker to generate the connections from.
file – A JSON or TOML file containing connection information. @forcpponly
err – [inout] A helics_error object, can be NULL if the errors are to be ignored. @endforcpponly
-
void helicsBrokerSetGlobal(helics_broker broker, const char *valueName, const char *value, helics_error *err)¶
Set a federation global value.
This overwrites any previous value for this name.
- Parameters
broker – The broker to set the global through.
valueName – The name of the global to set.
value – The value of the global. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsBrokerSetLogFile(helics_broker broker, const char *logFileName, helics_error *err)¶
Set the log file on a broker.
- Parameters
broker – The broker to set the log file for.
logFileName – The name of the file to log to. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
helics_bool helicsBrokerWaitForDisconnect(helics_broker broker, int msToWait, helics_error *err)¶
Wait for the broker to disconnect.
- Parameters
broker – The broker to wait for.
msToWait – The time out in millisecond (<0 for infinite timeout). @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
helics_true if the disconnect was successful, helics_false if there was a timeout.
-
void helicsBrokerSetLoggingCallback(helics_broker broker, void (*logger)(int loglevel, const char *identifier, const char *message, void *userData), void *userdata, helics_error *err)¶
Set the logging callback to a broker.
Add a logging callback function to a broker. The logging callback will be called when a message flows into a broker from the core or from a broker.
- Parameters
broker – The broker object in which to set the callback.
logger – A callback with signature void(int, const char *, const char *, void *); the function arguments are loglevel, an identifier, a message string, and a pointer to user data.
userdata – A pointer to user data that is passed to the function when executing. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
Core¶
-
void helicsCoreAddDestinationFilterToEndpoint(helics_core core, const char *filter, const char *endpoint, helics_error *err)¶
Link a named filter to a destination endpoint.
- Parameters
core – The core to generate the connection from.
filter – The name of the filter (cannot be NULL).
endpoint – The name of the endpoint to filter the data going to (cannot be NULL). @forcpponly
err – [inout] A helics_error object, can be NULL if the errors are to be ignored. @endforcpponly
-
void helicsCoreAddSourceFilterToEndpoint(helics_core core, const char *filter, const char *endpoint, helics_error *err)¶
Link a named filter to a source endpoint.
- Parameters
core – The core to generate the connection from.
filter – The name of the filter (cannot be NULL).
endpoint – The name of the endpoint to filter the data from (cannot be NULL). @forcpponly
err – [inout] A helics_error object, can be NULL if the errors are to be ignored. @endforcpponly
-
helics_core helicsCoreClone(helics_core core, helics_error *err)¶
Create a new reference to an existing core.
This will create a new broker object that references the existing broker. The new broker object must be freed as well.
- Parameters
core – An existing helics_core. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
A new reference to the same broker.
-
helics_bool helicsCoreConnect(helics_core core, helics_error *err)¶
Connect a core to the federate based on current configuration.
- Parameters
core – The core to connect. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
helics_false if not connected, helics_true if it is connected.
-
void helicsCoreDataLink(helics_core core, const char *source, const char *target, helics_error *err)¶
Link a named publication and named input using a core.
- Parameters
core – The core to generate the connection from.
source – The name of the publication (cannot be NULL).
target – The name of the target to send the publication data (cannot be NULL). @forcpponly
err – [inout] A helics_error object, can be NULL if the errors are to be ignored. @endforcpponly
-
void helicsCoreDestroy(helics_core core)¶
Disconnect and free a core.
-
void helicsCoreDisconnect(helics_core core, helics_error *err)¶
Disconnect a core from the federation.
- Parameters
core – The core to query. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsCoreFree(helics_core core)¶
Release the memory associated with a core.
-
const char *helicsCoreGetAddress(helics_core core)¶
Get the network address associated with a core.
- Parameters
core – The core to query.
- Returns
A string with the network address of the broker.
-
const char *helicsCoreGetIdentifier(helics_core core)¶
Get an identifier for the core.
- Parameters
core – The core to query.
- Returns
A string with the identifier of the core.
-
helics_bool helicsCoreIsConnected(helics_core core)¶
Check if a core is connected.
A connected core implies it is attached to federates or federates could be attached to it
- Returns
helics_false if not connected, helics_true if it is connected.
-
helics_bool helicsCoreIsValid(helics_core core)¶
Check if a core object is a valid object.
- Parameters
core – The helics_core object to test.
-
void helicsCoreMakeConnections(helics_core core, const char *file, helics_error *err)¶
Load a file containing connection information.
- Parameters
core – The core to generate the connections from.
file – A JSON or TOML file containing connection information. @forcpponly
err – [inout] A helics_error object, can be NULL if the errors are to be ignored. @endforcpponly
-
helics_filter helicsCoreRegisterCloningFilter(helics_core core, const char *name, helics_error *err)¶
Create a cloning Filter on the specified core.
Cloning filters copy a message and send it to multiple locations, source and destination can be added through other functions.
- Parameters
core – The core to register through.
name – The name of the filter (can be NULL). @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
A helics_filter object.
-
helics_filter helicsCoreRegisterFilter(helics_core core, helics_filter_type type, const char *name, helics_error *err)¶
Create a source Filter on the specified core.
Filters can be created through a federate or a core, linking through a federate allows a few extra features of name matching to function on the federate interface but otherwise equivalent behavior.
- Parameters
core – The core to register through.
type – The type of filter to create /ref helics_filter_type.
name – The name of the filter (can be NULL). @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
A helics_filter object.
-
void helicsCoreSetGlobal(helics_core core, const char *valueName, const char *value, helics_error *err)¶
Set a global value in a core.
This overwrites any previous value for this name.
- Parameters
core – The core to set the global through.
valueName – The name of the global to set.
value – The value of the global. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsCoreSetLogFile(helics_core core, const char *logFileName, helics_error *err)¶
Set the log file on a core.
- Parameters
core – The core to set the log file for.
logFileName – The name of the file to log to. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsCoreSetReadyToInit(helics_core core, helics_error *err)¶
Set the core to ready for init.
This function is used for cores that have filters but no federates so there needs to be a direct signal to the core to trigger the federation initialization.
- Parameters
core – The core object to enable init values for. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
helics_bool helicsCoreWaitForDisconnect(helics_core core, int msToWait, helics_error *err)¶
Wait for the core to disconnect.
- Parameters
core – The core to wait for.
msToWait – The time out in millisecond (<0 for infinite timeout). @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
helics_true if the disconnect was successful, helics_false if there was a timeout.
-
void helicsCoreSetLoggingCallback(helics_core core, void (*logger)(int loglevel, const char *identifier, const char *message, void *userData), void *userdata, helics_error *err)¶
Set the logging callback for a core.
Add a logging callback function to a core. The logging callback will be called when a message flows into a core from the core or from a broker.
- Parameters
core – The core object in which to set the callback.
logger – A callback with signature void(int, const char *, const char *, void *); The function arguments are loglevel, an identifier, a message string, and a pointer to user data.
userdata – A pointer to user data that is passed to the function when executing. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
Endpoint¶
Warning
doxygenfunction: Unable to resolve function “helicsEndpointClearMessages” with arguments “None”. Candidate function could not be parsed. Parsing error is Error when parsing function declaration. If the function has no return type: Error in declarator or parameters-and-qualifiers Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 25] HELICS_DEPRECATED_EXPORT void helicsEndpointClearMessages (helics_endpoint endpoint) ————————-^ If the function has a return type: Error in declarator or parameters-and-qualifiers If pointer to member declarator: Invalid C++ declaration: Expected identifier in nested name, got keyword: void [error at 29] HELICS_DEPRECATED_EXPORT void helicsEndpointClearMessages (helics_endpoint endpoint) —————————–^ If declarator-id: Invalid C++ declaration: Expected identifier in nested name, got keyword: void [error at 29] HELICS_DEPRECATED_EXPORT void helicsEndpointClearMessages (helics_endpoint endpoint) —————————–^
-
helics_message_object helicsEndpointCreateMessageObject(helics_endpoint endpoint, helics_error *err)¶
Create a new empty message object.
The message is empty and isValid will return false since there is no data associated with the message yet.
- Parameters
endpoint – The endpoint object to associate the message with. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
- Returns
A new helics_message_object.
-
const char *helicsEndpointGetDefaultDestination(helics_endpoint endpoint)¶
Get the default destination for an endpoint.
- Parameters
endpoint – The endpoint to set the destination for.
- Returns
A string with the default destination.
-
const char *helicsEndpointGetInfo(helics_endpoint end)¶
Get the data in the info field of a filter.
- Parameters
end – The filter to query.
- Returns
A string with the info field string.
Warning
doxygenfunction: Unable to resolve function “helicsEndpointGetMessage” with arguments “None”. Candidate function could not be parsed. Parsing error is Error when parsing function declaration. If the function has no return type: Error in declarator or parameters-and-qualifiers Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 25] HELICS_DEPRECATED_EXPORT helics_message helicsEndpointGetMessage (helics_endpoint endpoint) ————————-^ If the function has a return type: Error in declarator or parameters-and-qualifiers If pointer to member declarator: Invalid C++ declaration: Expected ‘::’ in pointer to member (function). [error at 40] HELICS_DEPRECATED_EXPORT helics_message helicsEndpointGetMessage (helics_endpoint endpoint) —————————————-^ If declarator-id: Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 40] HELICS_DEPRECATED_EXPORT helics_message helicsEndpointGetMessage (helics_endpoint endpoint) —————————————-^
-
helics_message_object helicsEndpointGetMessageObject(helics_endpoint endpoint)¶
Receive a packet from a particular endpoint.
- Parameters
endpoint – [in] The identifier for the endpoint.
- Returns
A message object.
-
const char *helicsEndpointGetName(helics_endpoint endpoint)¶
Get the name of an endpoint.
- Parameters
endpoint – The endpoint object in question.
- Returns
The name of the endpoint.
-
int helicsEndpointGetOption(helics_endpoint endpoint, int option)¶
Set a handle option on an endpoint.
- Parameters
endpoint – The endpoint to modify.
option – Integer code for the option to set /ref helics_handle_options.
- Returns
the value of the option, for boolean options will be 0 or 1
-
const char *helicsEndpointGetType(helics_endpoint endpoint)¶
Get the type specified for an endpoint.
- Parameters
endpoint – The endpoint object in question.
- Returns
The defined type of the endpoint.
-
helics_bool helicsEndpointHasMessage(helics_endpoint endpoint)¶
Check if a given endpoint has any unread messages.
- Parameters
endpoint – The endpoint to check.
- Returns
helics_true if the endpoint has a message, helics_false otherwise.
-
helics_bool helicsEndpointIsValid(helics_endpoint endpoint)¶
Check if an endpoint is valid.
- Parameters
endpoint – The endpoint object to check.
- Returns
helics_true if the Endpoint object represents a valid endpoint.
Warning
doxygenfunction: Unable to resolve function “helicsEndpointPendingMessages” with arguments “None”. Candidate function could not be parsed. Parsing error is Error when parsing function declaration. If the function has no return type: Error in declarator or parameters-and-qualifiers Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 25] HELICS_DEPRECATED_EXPORT int helicsEndpointPendingMessages (helics_endpoint endpoint) ————————-^ If the function has a return type: Error in declarator or parameters-and-qualifiers If pointer to member declarator: Invalid C++ declaration: Expected identifier in nested name, got keyword: int [error at 28] HELICS_DEPRECATED_EXPORT int helicsEndpointPendingMessages (helics_endpoint endpoint) —————————-^ If declarator-id: Invalid C++ declaration: Expected identifier in nested name, got keyword: int [error at 28] HELICS_DEPRECATED_EXPORT int helicsEndpointPendingMessages (helics_endpoint endpoint) —————————-^
-
void helicsEndpointSendEventRaw(helics_endpoint endpoint, const char *dst, const void *data, int inputDataLength, helics_time time, helics_error *err)¶
Send a message at a specific time to the specified destination.
- Parameters
endpoint – The endpoint to send the data from.
dst – The target destination. @forcpponly nullptr to use the default destination. @endforcpponly @beginpythononly “” to use the default destination. @endpythononly
data – The data to send. @forcpponly
inputDataLength – The length of the data to send. @endforcpponly
time – The time the message should be sent. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
Warning
doxygenfunction: Unable to resolve function “helicsEndpointSendMessage” with arguments “None”. Candidate function could not be parsed. Parsing error is Error when parsing function declaration. If the function has no return type: Error in declarator or parameters-and-qualifiers Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 25] HELICS_DEPRECATED_EXPORT void helicsEndpointSendMessage (helics_endpoint endpoint, helics_message *message, helics_error *err) ————————-^ If the function has a return type: Error in declarator or parameters-and-qualifiers If pointer to member declarator: Invalid C++ declaration: Expected identifier in nested name, got keyword: void [error at 29] HELICS_DEPRECATED_EXPORT void helicsEndpointSendMessage (helics_endpoint endpoint, helics_message *message, helics_error *err) —————————–^ If declarator-id: Invalid C++ declaration: Expected identifier in nested name, got keyword: void [error at 29] HELICS_DEPRECATED_EXPORT void helicsEndpointSendMessage (helics_endpoint endpoint, helics_message *message, helics_error *err) —————————–^
-
void helicsEndpointSendMessageObject(helics_endpoint endpoint, helics_message_object message, helics_error *err)¶
Send a message object from a specific endpoint.
- Parameters
endpoint – The endpoint to send the data from.
message – The actual message to send which will be copied. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsEndpointSendMessageObjectZeroCopy(helics_endpoint endpoint, helics_message_object message, helics_error *err)¶
Send a message object from a specific endpoint, the message will not be copied and the message object will no longer be valid after the call.
- Parameters
endpoint – The endpoint to send the data from.
message – The actual message to send which will be copied. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsEndpointSendMessageRaw(helics_endpoint endpoint, const char *dst, const void *data, int inputDataLength, helics_error *err)¶
Send a message to the specified destination.
- Parameters
endpoint – The endpoint to send the data from.
dst – The target destination. @forcpponly nullptr to use the default destination. @endforcpponly @beginpythononly “” to use the default destination. @endpythononly
data – The data to send. @forcpponly
inputDataLength – The length of the data to send.
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsEndpointSetDefaultDestination(helics_endpoint endpoint, const char *dst, helics_error *err)¶
Set the default destination for an endpoint if no other endpoint is given.
- Parameters
endpoint – The endpoint to set the destination for.
dst – A string naming the desired default endpoint. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsEndpointSetInfo(helics_endpoint endpoint, const char *info, helics_error *err)¶
Set the data in the info field for a filter.
- Parameters
endpoint – The endpoint to query.
info – The string to set. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsEndpointSetOption(helics_endpoint endpoint, int option, int value, helics_error *err)¶
Set a handle option on an endpoint.
- Parameters
endpoint – The endpoint to modify.
option – Integer code for the option to set /ref helics_handle_options.
value – The value to set the option to. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsEndpointSubscribe(helics_endpoint endpoint, const char *key, helics_error *err)¶
Subscribe an endpoint to a publication.
- Parameters
endpoint – The endpoint to use.
key – The name of the publication. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
FederateInfo¶
-
helics_federate_info helicsFederateInfoClone(helics_federate_info fi, helics_error *err)¶
Create a federate info object from an existing one and clone the information.
- Parameters
fi – A federateInfo object to duplicate. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
A helics_federate_info object which is a reference to the created object.
-
void helicsFederateInfoFree(helics_federate_info fi)¶
Delete the memory associated with a federate info object.
-
void helicsFederateInfoLoadFromArgs(helics_federate_info fi, int argc, const char *const *argv, helics_error *err)¶
Load federate info from command line arguments.
- Parameters
fi – A federateInfo object.
argc – The number of command line arguments.
argv – An array of strings from the command line. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateInfoSetBroker(helics_federate_info fi, const char *broker, helics_error *err)¶
Set the name or connection information for a broker.
This is only used if the core is automatically created, the broker information will be transferred to the core for connection.
- Parameters
fi – The federate info object to alter.
broker – A string which defines the connection information for a broker either a name or an address. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateInfoSetBrokerInitString(helics_federate_info fi, const char *brokerInit, helics_error *err)¶
Set the initialization string that a core will pass to a generated broker usually in the form of command line arguments.
- Parameters
fi – The federate info object to alter.
brokerInit – A string with command line arguments for a generated broker. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateInfoSetBrokerKey(helics_federate_info fi, const char *brokerkey, helics_error *err)¶
Set the key for a broker connection.
This is only used if the core is automatically created, the broker information will be transferred to the core for connection.
- Parameters
fi – The federate info object to alter.
brokerkey – A string containing a key for the broker to connect. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateInfoSetBrokerPort(helics_federate_info fi, int brokerPort, helics_error *err)¶
Set the port to use for the broker.
This is only used if the core is automatically created, the broker information will be transferred to the core for connection. This will only be useful for network broker connections.
- Parameters
fi – The federate info object to alter.
brokerPort – The integer port number to use for connection with a broker. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateInfoSetCoreInitString(helics_federate_info fi, const char *coreInit, helics_error *err)¶
Set the initialization string for the core usually in the form of command line arguments.
- Parameters
fi – The federate info object to alter.
coreInit – A string containing command line arguments to be passed to the core. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateInfoSetCoreName(helics_federate_info fi, const char *corename, helics_error *err)¶
Set the name of the core to link to for a federate.
- Parameters
fi – The federate info object to alter.
corename – The identifier for a core to link to. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateInfoSetCoreType(helics_federate_info fi, int coretype, helics_error *err)¶
Set the core type by integer code.
Valid values available by definitions in api-data.h.
- Parameters
fi – The federate info object to alter.
coretype – An numerical code for a core type see /ref helics_core_type. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateInfoSetCoreTypeFromString(helics_federate_info fi, const char *coretype, helics_error *err)¶
Set the core type from a string.
- Parameters
fi – The federate info object to alter.
coretype – A string naming a core type. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateInfoSetFlagOption(helics_federate_info fi, int flag, helics_bool value, helics_error *err)¶
Set a flag in the info structure.
Valid flags are available /ref helics_federate_flags.
- Parameters
fi – The federate info object to alter.
flag – A numerical index for a flag.
value – The desired value of the flag helics_true or helics_false. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateInfoSetIntegerProperty(helics_federate_info fi, int intProperty, int propertyValue, helics_error *err)¶
Set an integer property for a federate.
Set known properties.
- Parameters
fi – The federateInfo object to alter.
intProperty – An int identifying the property.
propertyValue – The value to set the property to. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateInfoSetLocalPort(helics_federate_info fi, const char *localPort, helics_error *err)¶
Set the local port to use.
This is only used if the core is automatically created, the port information will be transferred to the core for connection.
- Parameters
fi – The federate info object to alter.
localPort – A string with the port information to use as the local server port can be a number or “auto” or “os_local”. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateInfoSetSeparator(helics_federate_info fi, char separator, helics_error *err)¶
Set the separator character in the info structure.
The separator character is the separation character for local publications/endpoints in creating their global name. For example if the separator character is ‘/’ then a local endpoint would have a globally reachable name of fedName/localName.
- Parameters
fi – The federate info object to alter.
separator – The character to use as a separator. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateInfoSetTimeProperty(helics_federate_info fi, int timeProperty, helics_time propertyValue, helics_error *err)¶
Set the output delay for a federate.
- Parameters
fi – The federate info object to alter.
timeProperty – An integer representation of the time based property to set see /ref helics_properties.
propertyValue – The value of the property to set the timeProperty to. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
Federate¶
-
void helicsFederateAddDependency(helics_federate fed, const char *fedName, helics_error *err)¶
Add a time dependency for a federate. The federate will depend on the given named federate for time synchronization.
- Parameters
fed – The federate to add the dependency for.
fedName – The name of the federate to depend on. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsFederateClearMessages(helics_federate fed)¶
Clear all stored messages from a federate.
This clears messages retrieved through helicsFederateGetMessage or helicsFederateGetMessageObject
- Parameters
fed – The federate to clear the message for.
-
void helicsFederateClearUpdates(helics_federate fed)¶
Clear all the update flags from a federates inputs.
- Parameters
fed – The value federate object for which to clear update flags.
-
helics_federate helicsFederateClone(helics_federate fed, helics_error *err)¶
Create a new reference to an existing federate.
This will create a new helics_federate object that references the existing federate. The new object must be freed as well.
- Parameters
fed – An existing helics_federate. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
A new reference to the same federate.
-
helics_message_object helicsFederateCreateMessageObject(helics_federate fed, helics_error *err)¶
Create a new empty message object.
The message is empty and isValid will return false since there is no data associated with the message yet.
- Parameters
fed – the federate object to associate the message with @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
- Returns
A helics_message_object containing the message data.
-
void helicsFederateDestroy(helics_federate fed)¶
Disconnect and free a federate.
-
void helicsFederateEnterExecutingMode(helics_federate fed, helics_error *err)¶
Request that the federate enter the Execution mode.
This call is blocking until granted entry by the core object. On return from this call the federate will be at time 0. For an asynchronous alternative call see /ref helicsFederateEnterExecutingModeAsync.
- Parameters
fed – A federate to change modes. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateEnterExecutingModeAsync(helics_federate fed, helics_error *err)¶
Request that the federate enter the Execution mode.
This call is non-blocking and will return immediately. Call /ref helicsFederateEnterExecutingModeComplete to finish the call sequence.
- Parameters
fed – The federate object to complete the call. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateEnterExecutingModeComplete(helics_federate fed, helics_error *err)¶
Complete the call to /ref helicsFederateEnterExecutingModeAsync.
- Parameters
fed – The federate object to complete the call. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
helics_iteration_result helicsFederateEnterExecutingModeIterative(helics_federate fed, helics_iteration_request iterate, helics_error *err)¶
Request an iterative time.
This call allows for finer grain control of the iterative process than /ref helicsFederateRequestTime. It takes a time and iteration request, and returns a time and iteration status.
- Parameters
fed – The federate to make the request of.
iterate – The requested iteration mode. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
An iteration structure with field containing the time and iteration status.
-
void helicsFederateEnterExecutingModeIterativeAsync(helics_federate fed, helics_iteration_request iterate, helics_error *err)¶
Request an iterative entry to the execution mode.
This call allows for finer grain control of the iterative process than /ref helicsFederateRequestTime. It takes a time and iteration request, and returns a time and iteration status
- Parameters
fed – The federate to make the request of.
iterate – The requested iteration mode. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
helics_iteration_result helicsFederateEnterExecutingModeIterativeComplete(helics_federate fed, helics_error *err)¶
Complete the asynchronous iterative call into ExecutionMode.
- Parameters
fed – The federate to make the request of. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
An iteration object containing the iteration time and iteration_status.
-
void helicsFederateEnterInitializingMode(helics_federate fed, helics_error *err)¶
Enter the initialization state of a federate.
The initialization state allows initial values to be set and received if the iteration is requested on entry to the execution state. This is a blocking call and will block until the core allows it to proceed.
- Parameters
fed – The federate to operate on. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateEnterInitializingModeAsync(helics_federate fed, helics_error *err)¶
Non blocking alternative to helicsFederateEnterInitializingMode.
The function helicsFederateEnterInitializationModeFinalize must be called to finish the operation.
- Parameters
fed – The federate to operate on. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateEnterInitializingModeComplete(helics_federate fed, helics_error *err)¶
Finalize the entry to initialize mode that was initiated with /ref heliceEnterInitializingModeAsync.
- Parameters
fed – The federate desiring to complete the initialization step. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateFinalize(helics_federate fed, helics_error *err)¶
Finalize the federate. This function halts all communication in the federate and disconnects it from the core.
-
void helicsFederateFinalizeAsync(helics_federate fed, helics_error *err)¶
Finalize the federate in an async call.
-
void helicsFederateFinalizeComplete(helics_federate fed, helics_error *err)¶
Complete the asynchronous finalize call.
-
void helicsFederateFree(helics_federate fed)¶
Release the memory associated with a federate.
-
helics_core helicsFederateGetCoreObject(helics_federate fed, helics_error *err)¶
Get the core object associated with a federate.
- Parameters
fed – A federate object. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
A core object, nullptr if invalid.
-
helics_time helicsFederateGetCurrentTime(helics_federate fed, helics_error *err)¶
Get the current time of the federate.
- Parameters
fed – The federate object to query. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
The current time of the federate.
-
helics_endpoint helicsFederateGetEndpoint(helics_federate fed, const char *name, helics_error *err)¶
Get an endpoint object from a name.
- Parameters
fed – The message federate object to use to get the endpoint.
name – The name of the endpoint. @forcpponly
err – [inout] The error object to complete if there is an error. @endforcpponly
- Returns
A helics_endpoint object. @forcpponly The object will not be valid and err will contain an error code if no endpoint with the specified name exists. @endforcpponly
-
helics_endpoint helicsFederateGetEndpointByIndex(helics_federate fed, int index, helics_error *err)¶
Get an endpoint by its index, typically already created via registerInterfaces file or something of that nature.
- Parameters
fed – The federate object in which to create a publication.
index – The index of the publication to get. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
A helics_endpoint. @forcpponly It will be NULL if given an invalid index. @endforcpponly
-
int helicsFederateGetEndpointCount(helics_federate fed)¶
Get the number of endpoints in a federate.
- Parameters
fed – The message federate to query.
- Returns
(-1) if fed was not a valid federate, otherwise returns the number of endpoints.
-
helics_filter helicsFederateGetFilter(helics_federate fed, const char *name, helics_error *err)¶
Get a filter by its name, typically already created via registerInterfaces file or something of that nature.
- Parameters
fed – The federate object to use to get the filter.
name – The name of the filter. @forcpponly
err – [inout] The error object to complete if there is an error. @endforcpponly
- Returns
A helics_filter object, the object will not be valid and err will contain an error code if no filter with the specified name exists.
-
helics_filter helicsFederateGetFilterByIndex(helics_federate fed, int index, helics_error *err)¶
Get a filter by its index, typically already created via registerInterfaces file or something of that nature.
- Parameters
fed – The federate object in which to create a publication.
index – The index of the publication to get. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
A helics_filter, which will be NULL if an invalid index is given.
-
int helicsFederateGetFilterCount(helics_federate fed)¶
Get the number of filters registered through a federate.
- Parameters
fed – The federate object to use to get the filter.
- Returns
A count of the number of filters registered through a federate.
-
helics_bool helicsFederateGetFlagOption(helics_federate fed, int flag, helics_error *err)¶
Get a flag value for a federate.
- Parameters
fed – The federate to get the flag for.
flag – The flag to query. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
The value of the flag.
-
helics_input helicsFederateGetInput(helics_federate fed, const char *key, helics_error *err)¶
Get an input object from a key.
- Parameters
fed – The value federate object to use to get the publication.
key – The name of the input. @forcpponly
err – [inout] The error object to complete if there is an error. @endforcpponly
- Returns
A helics_input object, the object will not be valid and err will contain an error code if no input with the specified key exists.
-
helics_input helicsFederateGetInputByIndex(helics_federate fed, int index, helics_error *err)¶
Get an input by its index, typically already created via registerInterfaces file or something of that nature.
- Parameters
fed – The federate object in which to create a publication.
index – The index of the publication to get. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
A helics_input, which will be NULL if an invalid index.
-
int helicsFederateGetInputCount(helics_federate fed)¶
Get the number of subscriptions in a federate.
- Returns
(-1) if fed was not a valid federate otherwise returns the number of subscriptions.
-
int helicsFederateGetIntegerProperty(helics_federate fed, int intProperty, helics_error *err)¶
Get the current value of an integer property (such as a logging level).
- Parameters
fed – The federate to get the flag for.
intProperty – A code for the property to set /ref helics_handle_options. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
The value of the property.
Warning
doxygenfunction: Unable to resolve function “helicsFederateGetMessage” with arguments “None”. Candidate function could not be parsed. Parsing error is Error when parsing function declaration. If the function has no return type: Error in declarator or parameters-and-qualifiers Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 25] HELICS_DEPRECATED_EXPORT helics_message helicsFederateGetMessage (helics_federate fed) ————————-^ If the function has a return type: Error in declarator or parameters-and-qualifiers If pointer to member declarator: Invalid C++ declaration: Expected ‘::’ in pointer to member (function). [error at 40] HELICS_DEPRECATED_EXPORT helics_message helicsFederateGetMessage (helics_federate fed) —————————————-^ If declarator-id: Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 40] HELICS_DEPRECATED_EXPORT helics_message helicsFederateGetMessage (helics_federate fed) —————————————-^
-
helics_message_object helicsFederateGetMessageObject(helics_federate fed)¶
Receive a communication message for any endpoint in the federate.
The return order will be in order of endpoint creation. So all messages that are available for the first endpoint, then all for the second, and so on. Within a single endpoint, the messages are ordered by time, then source_id, then order of arrival.
- Returns
A helics_message_object which references the data in the message.
-
const char *helicsFederateGetName(helics_federate fed)¶
Get the name of the federate.
- Parameters
fed – The federate object to query.
- Returns
A pointer to a string with the name.
-
helics_publication helicsFederateGetPublication(helics_federate fed, const char *key, helics_error *err)¶
Get a publication object from a key.
- Parameters
fed – The value federate object to use to get the publication.
key – The name of the publication. @forcpponly
err – [inout] The error object to complete if there is an error. @endforcpponly
- Returns
A helics_publication object, the object will not be valid and err will contain an error code if no publication with the specified key exists.
-
helics_publication helicsFederateGetPublicationByIndex(helics_federate fed, int index, helics_error *err)¶
Get a publication by its index, typically already created via registerInterfaces file or something of that nature.
- Parameters
fed – The federate object in which to create a publication.
index – The index of the publication to get. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
A helics_publication.
-
int helicsFederateGetPublicationCount(helics_federate fed)¶
Get the number of publications in a federate.
- Returns
(-1) if fed was not a valid federate otherwise returns the number of publications.
-
helics_federate_state helicsFederateGetState(helics_federate fed, helics_error *err)¶
Get the current state of a federate.
- Parameters
fed – The federate to query. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
State the resulting state if void return helics_ok.
-
helics_input helicsFederateGetSubscription(helics_federate fed, const char *key, helics_error *err)¶
Get an input object from a subscription target.
- Parameters
fed – The value federate object to use to get the publication.
key – The name of the publication that a subscription is targeting. @forcpponly
err – [inout] The error object to complete if there is an error. @endforcpponly
- Returns
A helics_input object, the object will not be valid and err will contain an error code if no input with the specified key exists.
-
helics_time helicsFederateGetTimeProperty(helics_federate fed, int timeProperty, helics_error *err)¶
Get the current value of a time based property in a federate.
- Parameters
fed – The federate query.
timeProperty – The property to query. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateGlobalError(helics_federate fed, int errorCode, const char *errorString)¶
Generate a global error from a federate.
A global error halts the co-simulation completely.
- Parameters
fed – The federate to create an error in.
errorCode – The integer code for the error.
errorString – A string describing the error.
-
helics_bool helicsFederateHasMessage(helics_federate fed)¶
Check if the federate has any outstanding messages.
- Parameters
fed – The federate to check.
- Returns
helics_true if the federate has a message waiting, helics_false otherwise.
-
helics_bool helicsFederateIsAsyncOperationCompleted(helics_federate fed, helics_error *err)¶
Check if the current Asynchronous operation has completed.
- Parameters
fed – The federate to operate on. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
helics_false if not completed, helics_true if completed.
-
helics_bool helicsFederateIsValid(helics_federate fed)¶
Check if a federate_object is valid.
- Returns
helics_true if the federate is a valid active federate, helics_false otherwise
-
void helicsFederateLocalError(helics_federate fed, int errorCode, const char *errorString)¶
Generate a local error in a federate.
This will propagate through the co-simulation but not necessarily halt the co-simulation, it has a similar effect to finalize but does allow some interaction with a core for a brief time.
- Parameters
fed – The federate to create an error in.
errorCode – The integer code for the error.
errorString – A string describing the error.
-
void helicsFederateLogDebugMessage(helics_federate fed, const char *logmessage, helics_error *err)¶
Log a debug message through a federate.
- Parameters
fed – The federate to log the debug message through.
logmessage – The message to put in the log. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsFederateLogErrorMessage(helics_federate fed, const char *logmessage, helics_error *err)¶
Log an error message through a federate.
- Parameters
fed – The federate to log the error message through.
logmessage – The message to put in the log. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsFederateLogInfoMessage(helics_federate fed, const char *logmessage, helics_error *err)¶
Log an info message through a federate.
- Parameters
fed – The federate to log the info message through.
logmessage – The message to put in the log. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsFederateLogLevelMessage(helics_federate fed, int loglevel, const char *logmessage, helics_error *err)¶
Log a message through a federate.
- Parameters
fed – The federate to log the message through.
loglevel – The level of the message to log see /ref helics_log_levels.
logmessage – The message to put in the log. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsFederateLogWarningMessage(helics_federate fed, const char *logmessage, helics_error *err)¶
Log a warning message through a federate.
- Parameters
fed – The federate to log the warning message through.
logmessage – The message to put in the log. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
Warning
doxygenfunction: Unable to resolve function “helicsFederatePendingMessages” with arguments “None”. Candidate function could not be parsed. Parsing error is Error when parsing function declaration. If the function has no return type: Error in declarator or parameters-and-qualifiers Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 25] HELICS_DEPRECATED_EXPORT int helicsFederatePendingMessages (helics_federate fed) ————————-^ If the function has a return type: Error in declarator or parameters-and-qualifiers If pointer to member declarator: Invalid C++ declaration: Expected identifier in nested name, got keyword: int [error at 28] HELICS_DEPRECATED_EXPORT int helicsFederatePendingMessages (helics_federate fed) —————————-^ If declarator-id: Invalid C++ declaration: Expected identifier in nested name, got keyword: int [error at 28] HELICS_DEPRECATED_EXPORT int helicsFederatePendingMessages (helics_federate fed) —————————-^
-
void helicsFederatePublishJSON(helics_federate fed, const char *json, helics_error *err)¶
Publish data contained in a JSON file or string.
- Parameters
fed – The value federate object through which to publish the data.
json – The publication file name or literal JSON data string. @forcpponly
err – [inout] The error object to complete if there is an error. @endforcpponly
-
helics_filter helicsFederateRegisterCloningFilter(helics_federate fed, const char *name, helics_error *err)¶
Create a cloning Filter on the specified federate.
Cloning filters copy a message and send it to multiple locations, source and destination can be added through other functions.
- Parameters
fed – The federate to register through.
name – The name of the filter (can be NULL). @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
A helics_filter object.
-
helics_endpoint helicsFederateRegisterEndpoint(helics_federate fed, const char *name, const char *type, helics_error *err)¶
Create an endpoint.
The endpoint becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for endpoints.
- Parameters
fed – The federate object in which to create an endpoint must have been created with helicsCreateMessageFederate or helicsCreateCombinationFederate.
name – The identifier for the endpoint. This will be prepended with the federate name for the global identifier.
type – A string describing the expected type of the publication (may be NULL). @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
An object containing the endpoint. @forcpponly nullptr on failure. @endforcpponly
-
helics_filter helicsFederateRegisterFilter(helics_federate fed, helics_filter_type type, const char *name, helics_error *err)¶
Create a source Filter on the specified federate.
Filters can be created through a federate or a core, linking through a federate allows a few extra features of name matching to function on the federate interface but otherwise equivalent behavior
- Parameters
fed – The federate to register through.
type – The type of filter to create /ref helics_filter_type.
name – The name of the filter (can be NULL). @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
A helics_filter object.
-
void helicsFederateRegisterFromPublicationJSON(helics_federate fed, const char *json, helics_error *err)¶
Register the publications via JSON publication string.
This would be the same JSON that would be used to publish data.
- Parameters
fed – The value federate object to use to register the publications.
json – The JSON publication string. @forcpponly
err – [inout] The error object to complete if there is an error. @endforcpponly
-
helics_filter helicsFederateRegisterGlobalCloningFilter(helics_federate fed, const char *name, helics_error *err)¶
Create a global cloning Filter on the specified federate.
Cloning filters copy a message and send it to multiple locations, source and destination can be added through other functions.
- Parameters
fed – The federate to register through.
name – The name of the filter (can be NULL). @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
A helics_filter object.
-
helics_endpoint helicsFederateRegisterGlobalEndpoint(helics_federate fed, const char *name, const char *type, helics_error *err)¶
Create an endpoint.
The endpoint becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for endpoints.
- Parameters
fed – The federate object in which to create an endpoint must have been created with helicsCreateMessageFederate or helicsCreateCombinationFederate.
name – The identifier for the endpoint, the given name is the global identifier.
type – A string describing the expected type of the publication (may be NULL). @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
An object containing the endpoint. @forcpponly nullptr on failure. @endforcpponly
-
helics_filter helicsFederateRegisterGlobalFilter(helics_federate fed, helics_filter_type type, const char *name, helics_error *err)¶
Create a global source filter through a federate.
Filters can be created through a federate or a core, linking through a federate allows a few extra features of name matching to function on the federate interface but otherwise equivalent behavior.
- Parameters
fed – The federate to register through.
type – The type of filter to create /ref helics_filter_type.
name – The name of the filter (can be NULL). @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
A helics_filter object.
-
helics_publication helicsFederateRegisterGlobalInput(helics_federate fed, const char *key, helics_data_type type, const char *units, helics_error *err)¶
Register a global named input.
The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.
- Parameters
fed – The federate object in which to create a publication.
key – The identifier for the publication.
type – A code identifying the type of the input see /ref helics_data_type for available options.
units – A string listing the units of the subscription maybe NULL. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
An object containing the publication.
-
helics_publication helicsFederateRegisterGlobalPublication(helics_federate fed, const char *key, helics_data_type type, const char *units, helics_error *err)¶
Register a global named publication with an arbitrary type.
The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.
- Parameters
fed – The federate object in which to create a publication.
key – The identifier for the publication.
type – A code identifying the type of the input see /ref helics_data_type for available options.
units – A string listing the units of the subscription (may be NULL). @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
An object containing the publication.
-
helics_publication helicsFederateRegisterGlobalTypeInput(helics_federate fed, const char *key, const char *type, const char *units, helics_error *err)¶
Register a global publication with an arbitrary type.
The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.
- Parameters
fed – The federate object in which to create a publication.
key – The identifier for the publication.
type – A string defining the type of the input.
units – A string listing the units of the subscription maybe NULL. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
An object containing the publication.
-
helics_publication helicsFederateRegisterGlobalTypePublication(helics_federate fed, const char *key, const char *type, const char *units, helics_error *err)¶
Register a global publication with a defined type.
The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.
- Parameters
fed – The federate object in which to create a publication.
key – The identifier for the publication.
type – A string describing the expected type of the publication.
units – A string listing the units of the subscription (may be NULL). @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
An object containing the publication.
-
helics_input helicsFederateRegisterInput(helics_federate fed, const char *key, helics_data_type type, const char *units, helics_error *err)¶
Register a named input.
The input becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions, inputs, and publications.
- Parameters
fed – The federate object in which to create an input.
key – The identifier for the publication the global input key will be prepended with the federate name.
type – A code identifying the type of the input see /ref helics_data_type for available options.
units – A string listing the units of the input (may be NULL). @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
An object containing the input.
-
void helicsFederateRegisterInterfaces(helics_federate fed, const char *file, helics_error *err)¶
Load interfaces from a file.
- Parameters
fed – The federate to which to load interfaces.
file – The name of a file to load the interfaces from either JSON, or TOML. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
helics_publication helicsFederateRegisterPublication(helics_federate fed, const char *key, helics_data_type type, const char *units, helics_error *err)¶
Register a publication with a known type.
The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.
- Parameters
fed – The federate object in which to create a publication.
key – The identifier for the publication the global publication key will be prepended with the federate name.
type – A code identifying the type of the input see /ref helics_data_type for available options.
units – A string listing the units of the subscription (may be NULL). @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
An object containing the publication.
-
helics_input helicsFederateRegisterSubscription(helics_federate fed, const char *key, const char *units, helics_error *err)¶
sub/pub registration Create a subscription.
The subscription becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.
- Parameters
fed – The federate object in which to create a subscription, must have been created with /ref helicsCreateValueFederate or /ref helicsCreateCombinationFederate.
key – The identifier matching a publication to get a subscription for.
units – A string listing the units of the subscription (may be NULL). @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
An object containing the subscription.
-
helics_input helicsFederateRegisterTypeInput(helics_federate fed, const char *key, const char *type, const char *units, helics_error *err)¶
Register an input with a defined type.
The input becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions, inputs, and publications.
- Parameters
fed – The federate object in which to create an input.
key – The identifier for the input.
type – A string describing the expected type of the input.
units – A string listing the units of the input maybe NULL. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
An object containing the publication.
-
helics_publication helicsFederateRegisterTypePublication(helics_federate fed, const char *key, const char *type, const char *units, helics_error *err)¶
Register a publication with a defined type.
The publication becomes part of the federate and is destroyed when the federate is freed so there are no separate free functions for subscriptions and publications.
- Parameters
fed – The federate object in which to create a publication.
key – The identifier for the publication.
type – A string labeling the type of the publication.
units – A string listing the units of the subscription (may be NULL). @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
An object containing the publication.
-
helics_time helicsFederateRequestNextStep(helics_federate fed, helics_error *err)¶
Request the next time step for federate execution.
Feds should have setup the period or minDelta for this to work well but it will request the next time step which is the current time plus the minimum time step.
- Parameters
fed – The federate to make the request of. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
The time granted to the federate, will return helics_time_maxtime if the simulation has terminated or is invalid
-
helics_time helicsFederateRequestTime(helics_federate fed, helics_time requestTime, helics_error *err)¶
Request the next time for federate execution.
- Parameters
fed – The federate to make the request of.
requestTime – The next requested time. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
The time granted to the federate, will return helics_time_maxtime if the simulation has terminated or is invalid.
-
helics_time helicsFederateRequestTimeAdvance(helics_federate fed, helics_time timeDelta, helics_error *err)¶
Request the next time for federate execution.
- Parameters
fed – The federate to make the request of.
timeDelta – The requested amount of time to advance. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
The time granted to the federate, will return helics_time_maxtime if the simulation has terminated or is invalid
-
void helicsFederateRequestTimeAsync(helics_federate fed, helics_time requestTime, helics_error *err)¶
Request the next time for federate execution in an asynchronous call.
Call /ref helicsFederateRequestTimeComplete to finish the call.
- Parameters
fed – The federate to make the request of.
requestTime – The next requested time. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
helics_time helicsFederateRequestTimeComplete(helics_federate fed, helics_error *err)¶
Complete an asynchronous requestTime call.
- Parameters
fed – The federate to make the request of. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
The time granted to the federate, will return helics_time_maxtime if the simulation has terminated.
-
helics_time helicsFederateRequestTimeIterative(helics_federate fed, helics_time requestTime, helics_iteration_request iterate, helics_iteration_result *outIteration, helics_error *err)¶
Request an iterative time.
This call allows for finer grain control of the iterative process than /ref helicsFederateRequestTime. It takes a time and and iteration request, and returns a time and iteration status.
- Parameters
fed – The federate to make the request of.
requestTime – The next desired time.
iterate – The requested iteration mode. @forcpponly
outIteration – [out] The iteration specification of the result. @endforcpponly @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
The granted time, will return helics_time_maxtime if the simulation has terminated along with the appropriate iteration result. @beginPythonOnly This function also returns the iteration specification of the result. @endPythonOnly
-
void helicsFederateRequestTimeIterativeAsync(helics_federate fed, helics_time requestTime, helics_iteration_request iterate, helics_error *err)¶
Request an iterative time through an asynchronous call.
This call allows for finer grain control of the iterative process than /ref helicsFederateRequestTime. It takes a time and iteration request, and returns a time and iteration status. Call /ref helicsFederateRequestTimeIterativeComplete to finish the process.
- Parameters
fed – The federate to make the request of.
requestTime – The next desired time.
iterate – The requested iteration mode. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
helics_time helicsFederateRequestTimeIterativeComplete(helics_federate fed, helics_iteration_result *outIterate, helics_error *err)¶
Complete an iterative time request asynchronous call.
- Parameters
fed – The federate to make the request of. @forcpponly
outIterate – [out] The iteration specification of the result.
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
The granted time, will return helics_time_maxtime if the simulation has terminated. @beginPythonOnly This function also returns the iteration specification of the result. @endPythonOnly
-
void helicsFederateSetFlagOption(helics_federate fed, int flag, helics_bool flagValue, helics_error *err)¶
Set a flag for the federate.
- Parameters
fed – The federate to alter a flag for.
flag – The flag to change.
flagValue – The new value of the flag. 0 for false, !=0 for true. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateSetGlobal(helics_federate fed, const char *valueName, const char *value, helics_error *err)¶
Set a federation global value through a federate.
This overwrites any previous value for this name.
- Parameters
fed – The federate to set the global through.
valueName – The name of the global to set.
value – The value of the global. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsFederateSetIntegerProperty(helics_federate fed, int intProperty, int propertyVal, helics_error *err)¶
Set an integer based property of a federate.
- Parameters
fed – The federate to change the property for.
intProperty – The property to set.
propertyVal – The value of the property. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateSetLogFile(helics_federate fed, const char *logFile, helics_error *err)¶
Set the logging file for a federate (actually on the core associated with a federate).
- Parameters
fed – The federate to set the log file for.
logFile – The name of the log file. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsFederateSetSeparator(helics_federate fed, char separator, helics_error *err)¶
Set the separator character in a federate.
The separator character is the separation character for local publications/endpoints in creating their global name. For example if the separator character is ‘/’ then a local endpoint would have a globally reachable name of fedName/localName.
- Parameters
fed – The federate info object to alter.
separator – The character to use as a separator. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsFederateSetTimeProperty(helics_federate fed, int timeProperty, helics_time time, helics_error *err)¶
Set a time based property for a federate.
- Parameters
fed – The federate object to set the property for.
timeProperty – A integer code for a time property.
time – The requested value of the property. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
Warning
doxygenfunction: Cannot find function “helicsFederateEnterInitializingModeCompleted” in doxygen xml output for project “helics” from directory: /home/docs/checkouts/readthedocs.org/user_builds/helics/checkouts/helics2/build-doxygen/docs/xml
-
void helicsFederateSetLoggingCallback(helics_federate fed, void (*logger)(int loglevel, const char *identifier, const char *message, void *userData), void *userdata, helics_error *err)¶
Set the logging callback for a federate.
Add a logging callback function to a federate. The logging callback will be called when a message flows into a federate from the core or from a federate.
- Parameters
fed – The federate object in which to create a subscription must have been created with helicsCreateValueFederate or helicsCreateCombinationFederate.
logger – A callback with signature void(int, const char *, const char *, void *); The function arguments are loglevel, an identifier string, a message string, and a pointer to user data.
userdata – A pointer to user data that is passed to the function when executing. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
Filter¶
-
void helicsFilterAddDeliveryEndpoint(helics_filter filt, const char *deliveryEndpoint, helics_error *err)¶
Add a delivery endpoint to a cloning filter.
All cloned messages are sent to the delivery address(es).
- Parameters
filt – The given filter.
deliveryEndpoint – The name of the endpoint to deliver messages to. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsFilterAddDestinationTarget(helics_filter filt, const char *dst, helics_error *err)¶
Add a destination target to a filter.
All messages going to a destination are copied to the delivery address(es).
- Parameters
filt – The given filter to add a destination target to.
dst – The name of the endpoint to add as a destination target. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsFilterAddSourceTarget(helics_filter filt, const char *source, helics_error *err)¶
Add a source target to a filter.
All messages coming from a source are copied to the delivery address(es).
- Parameters
filt – The given filter.
source – The name of the endpoint to add as a source target. @forcpponly.
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
const char *helicsFilterGetInfo(helics_filter filt)¶
Get the data in the info field of a filter.
- Parameters
filt – The given filter.
- Returns
A string with the info field string.
-
const char *helicsFilterGetName(helics_filter filt)¶
Get the name of the filter and store in the given string.
get the name of the filter
- Parameters
filt – The given filter.
- Returns
A string with the name of the filter.
-
int helicsFilterGetOption(helics_filter filt, int option)¶
Get a handle option for the filter.
- Parameters
filt – The given filter to query.
option – The option to query /ref helics_handle_options.
-
helics_bool helicsFilterIsValid(helics_filter filt)¶
Check if a filter is valid.
- Parameters
filt – The filter object to check.
- Returns
helics_true if the Filter object represents a valid filter.
-
void helicsFilterRemoveDeliveryEndpoint(helics_filter filt, const char *deliveryEndpoint, helics_error *err)¶
Remove a delivery destination from a cloning filter.
- Parameters
filt – The given filter (must be a cloning filter).
deliveryEndpoint – A string with the delivery endpoint to remove. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsFilterRemoveTarget(helics_filter filt, const char *target, helics_error *err)¶
Remove a destination target from a filter.
- Parameters
filt – The given filter.
target – The named endpoint to remove as a target. @forcpponly @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsFilterSet(helics_filter filt, const char *prop, double val, helics_error *err)¶
Set a property on a filter.
- Parameters
filt – The filter to modify.
prop – A string containing the property to set.
val – A numerical value for the property. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsFilterSetInfo(helics_filter filt, const char *info, helics_error *err)¶
Set the data in the info field for a filter.
- Parameters
filt – The given filter.
info – The string to set. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsFilterSetOption(helics_filter filt, int option, int value, helics_error *err)¶
Set the data in the info field for a filter.
- Parameters
filt – The given filter.
option – The option to set /ref helics_handle_options.
value – The value of the option commonly 0 for false 1 for true. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsFilterSetString(helics_filter filt, const char *prop, const char *val, helics_error *err)¶
Set a string property on a filter.
- Parameters
filt – The filter to modify.
prop – A string containing the property to set.
val – A string containing the new value. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsFilterSetCustomCallback(helics_filter filter, void (*filtCall)(helics_message_object message, void *userData), void *userdata, helics_error *err)¶
Set a general callback for a custom filter.
Add a custom filter callback for creating a custom filter operation in the C shared library.
- Parameters
filter – The filter object to set the callback for.
filtCall – A callback with signature helics_message_object(helics_message_object, void *); The function arguments are the message to filter and a pointer to user data. The filter should return a new message.
userdata – A pointer to user data that is passed to the function when executing. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
Input¶
-
void helicsInputAddTarget(helics_input ipt, const char *target, helics_error *err)¶
Add a publication to the list of data that an input subscribes to.
- Parameters
ipt – The named input to modify.
target – The name of a publication that an input should subscribe to. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsInputClearUpdate(helics_input ipt)¶
Clear the updated flag from an input.
-
helics_bool helicsInputGetBoolean(helics_input ipt, helics_error *err)¶
Get a boolean value from a subscription.
- Parameters
ipt – The input to get the data for. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
A boolean value of current input value.
-
char helicsInputGetChar(helics_input ipt, helics_error *err)¶
Get a single character value from an input.
- Parameters
ipt – The input to get the data for. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
The resulting character value. @forcpponly NAK (negative acknowledgment) symbol returned on error @endforcpponly
-
void helicsInputGetComplex(helics_input ipt, double *real, double *imag, helics_error *err)¶
Get a pair of double forming a complex number from a subscriptions.
@beginPythonOnly
- Parameters
ipt – The input to get the data for. @forcpponly
real – [out] Memory location to place the real part of a value.
imag – [out] Memory location to place the imaginary part of a value.
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. On error the values will not be altered. @endforcpponly
- Returns
a pair of floating point values that represent the real and imag values @endPythonOnly
-
helics_complex helicsInputGetComplexObject(helics_input ipt, helics_error *err)¶
Get a complex object from an input object.
- Parameters
ipt – The input to get the data for. @forcpponly
err – [inout] A helics error object, if the object is not empty the function is bypassed otherwise it is filled in if there is an error. @endforcpponly
- Returns
A helics_complex structure with the value.
-
double helicsInputGetDouble(helics_input ipt, helics_error *err)¶
Get a double value from a subscription.
- Parameters
ipt – The input to get the data for. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
The double value of the input.
-
const char *helicsInputGetExtractionUnits(helics_input ipt)¶
Get the units of an input.
The same as helicsInputGetUnits.
- Parameters
ipt – The input to query.
- Returns
A void enumeration, helics_ok if everything worked.
-
const char *helicsInputGetInfo(helics_input inp)¶
Get the data in the info field of an input.
- Parameters
inp – The input to query.
- Returns
A string with the info field string.
-
const char *helicsInputGetInjectionUnits(helics_input ipt)¶
Get the units of the publication that an input is linked to.
- Parameters
ipt – The input to query.
- Returns
A void enumeration, helics_ok if everything worked.
-
int64_t helicsInputGetInteger(helics_input ipt, helics_error *err)¶
Get an integer value from a subscription.
- Parameters
ipt – The input to get the data for. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
An int64_t value with the current value of the input.
-
const char *helicsInputGetKey(helics_input ipt)¶
Get the key of an input.
- Parameters
ipt – The input to query.
- Returns
A void enumeration, helics_ok if everything worked.
-
void helicsInputGetNamedPoint(helics_input ipt, char *outputString, int maxStringLength, int *actualLength, double *val, helics_error *err)¶
Get a named point from a subscription.
@beginPythonOnly
- Parameters
ipt – The input to get the result for. @forcpponly
outputString – [out] Storage for copying a null terminated string.
maxStringLength – The maximum size of information that str can hold.
actualLength – [out] The actual length of the string
val – [out] The double value for the named point.
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
a string and a double value for the named point @endPythonOnly
-
int helicsInputGetOption(helics_input inp, int option)¶
Get the current value of an input handle option
- Parameters
inp – The input to query.
option – Integer representation of the option in question see /ref helics_handle_options.
- Returns
An integer value with the current value of the given option.
-
const char *helicsInputGetPublicationType(helics_input ipt)¶
Get the type the publisher to an input is sending.
- Parameters
ipt – The input to query.
- Returns
A const char * with the type name.
-
void helicsInputGetRawValue(helics_input ipt, void *data, int maxDataLength, int *actualSize, helics_error *err)¶
Get the raw data for the latest value of a subscription.
@beginPythonOnly
- Parameters
ipt – The input to get the data for. @forcpponly
data – [out] The memory location of the data
maxDataLength – The maximum size of information that data can hold.
actualSize – [out] The actual length of data copied to data.
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
Raw string data. @endPythonOnly
-
int helicsInputGetRawValueSize(helics_input ipt)¶
Get the size of the raw value for subscription.
- Returns
The size of the raw data/string in bytes.
-
void helicsInputGetString(helics_input ipt, char *outputString, int maxStringLength, int *actualLength, helics_error *err)¶
Get a string value from a subscription.
@beginPythonOnly
- Parameters
ipt – The input to get the data for. @forcpponly
outputString – [out] Storage for copying a null terminated string.
maxStringLength – The maximum size of information that str can hold.
actualLength – [out] The actual length of the string.
err – [inout] Error term for capturing errors. @endforcpponly
- Returns
A string data @endPythonOnly
-
int helicsInputGetStringSize(helics_input ipt)¶
Get the size of a value for subscription assuming return as a string.
- Returns
The size of the string.
-
helics_time helicsInputGetTime(helics_input ipt, helics_error *err)¶
Get a time value from a subscription.
- Parameters
ipt – The input to get the data for. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
The resulting time value.
-
const char *helicsInputGetType(helics_input ipt)¶
Get the type of an input.
- Parameters
ipt – The input to query.
- Returns
A void enumeration, helics_ok if everything worked.
-
const char *helicsInputGetUnits(helics_input ipt)¶
Get the units of an input.
- Parameters
ipt – The input to query.
- Returns
A void enumeration, helics_ok if everything worked.
-
void helicsInputGetVector(helics_input ipt, double data[], int maxLength, int *actualSize, helics_error *err)¶
Get a vector from a subscription.
@beginPythonOnly
- Parameters
ipt – The input to get the result for. @forcpponly
data – [out] The location to store the data.
maxLength – The maximum size of the vector.
actualSize – [out] Location to place the actual length of the resulting vector.
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
a list of floating point values @endPythonOnly
-
int helicsInputGetVectorSize(helics_input ipt)¶
Get the size of a value for subscription assuming return as an array of doubles.
- Returns
The number of doubles in a returned vector.
-
helics_bool helicsInputIsUpdated(helics_input ipt)¶
Check if a particular subscription was updated.
- Returns
helics_true if it has been updated since the last value retrieval.
-
helics_bool helicsInputIsValid(helics_input ipt)¶
Check if an input is valid.
- Parameters
ipt – The input to check.
- Returns
helics_true if the Input object represents a valid input.
-
helics_time helicsInputLastUpdateTime(helics_input ipt)¶
Get the last time a subscription was updated.
-
void helicsInputSetDefaultBoolean(helics_input ipt, helics_bool val, helics_error *err)¶
Set the default as a boolean.
- Parameters
ipt – The input to set the default for.
val – The default boolean value. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsInputSetDefaultChar(helics_input ipt, char val, helics_error *err)¶
Set the default as a char.
- Parameters
ipt – The input to set the default for.
val – The default char value. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsInputSetDefaultComplex(helics_input ipt, double real, double imag, helics_error *err)¶
Set the default as a complex number.
- Parameters
ipt – The input to set the default for.
real – The default real value.
imag – The default imaginary value. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsInputSetDefaultDouble(helics_input ipt, double val, helics_error *err)¶
Set the default as a double.
- Parameters
ipt – The input to set the default for.
val – The default double value. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsInputSetDefaultInteger(helics_input ipt, int64_t val, helics_error *err)¶
Set the default as an integer.
- Parameters
ipt – The input to set the default for.
val – The default integer. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsInputSetDefaultNamedPoint(helics_input ipt, const char *str, double val, helics_error *err)¶
Set the default as a NamedPoint.
- Parameters
ipt – The input to set the default for.
str – A pointer to a string representing the name.
val – A double value for the value of the named point. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsInputSetDefaultRaw(helics_input ipt, const void *data, int inputDataLength, helics_error *err)¶
Set the default as a raw data array.
- Parameters
ipt – The input to set the default for.
data – A pointer to the raw data to use for the default. @forcpponly
inputDataLength – The size of the raw data.
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsInputSetDefaultString(helics_input ipt, const char *str, helics_error *err)¶
Set the default as a string.
- Parameters
ipt – The input to set the default for.
str – A pointer to the default string. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsInputSetDefaultTime(helics_input ipt, helics_time val, helics_error *err)¶
Set the default as a time.
- Parameters
ipt – The input to set the default for.
val – The default time value. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsInputSetDefaultVector(helics_input ipt, const double *vectorInput, int vectorLength, helics_error *err)¶
Set the default as a vector of doubles.
- Parameters
ipt – The input to set the default for.
vectorInput – A pointer to an array of double data.
vectorLength – The number of points to publish. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsInputSetInfo(helics_input inp, const char *info, helics_error *err)¶
Set the data in the info field for an input.
- Parameters
inp – The input to query.
info – The string to set. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsInputSetMinimumChange(helics_input inp, double tolerance, helics_error *err)¶
Set the minimum change detection tolerance.
- Parameters
inp – The input to modify.
tolerance – The tolerance level for registering an update, values changing less than this value will not show as being updated. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsInputSetOption(helics_input inp, int option, int value, helics_error *err)¶
Set an option on an input
- Parameters
inp – The input to query.
option – The option to set for the input /ref helics_handle_options.
value – The value to set the option to. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
Message¶
-
void helicsMessageAppendData(helics_message_object message, const void *data, int inputDataLength, helics_error *err)¶
Append data to the payload.
- Parameters
message – The message object in question.
data – A string containing the message data to append.
inputDataLength – The length of the data to input. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
helics_bool helicsMessageCheckFlag(helics_message_object message, int flag)¶
Check if a flag is set on a message.
- Parameters
message – The message object in question.
flag – The flag to check should be between [0,15].
- Returns
The flags associated with a message.
-
void helicsMessageClearFlags(helics_message_object message)¶
Clear the flags of a message.
- Parameters
message – The message object in question
-
helics_message_object helicsMessageClone(helics_message_object message, helics_error *err)¶
Clone a message object.
- Parameters
message – The message object to copy from. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsMessageCopy(helics_message_object src_message, helics_message_object dst_message, helics_error *err)¶
Copy a message object.
- Parameters
src_message – The message object to copy from.
dst_message – The message object to copy to. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsMessageFree(helics_message_object message)¶
Free a message object from memory
memory for message is managed so not using this function does not create memory leaks, this is an indication to the system that the memory for this message is done being used and can be reused for a new message.
helicsFederateClearMessages() can also be used to clear up all stored messages at once- Parameters
message – The message object to copy from.
-
const char *helicsMessageGetDestination(helics_message_object message)¶
Get the destination endpoint of a message.
- Parameters
message – The message object in question.
- Returns
A string with the destination endpoint.
-
int helicsMessageGetMessageID(helics_message_object message)¶
Get the messageID of a message.
- Parameters
message – The message object in question.
- Returns
The messageID.
-
const char *helicsMessageGetOriginalDestination(helics_message_object message)¶
Get the original destination endpoint of a message, the destination may have been modified by filters or other actions.
- Parameters
message – The message object in question.
- Returns
A string with the original destination of a message.
-
const char *helicsMessageGetOriginalSource(helics_message_object message)¶
Get the original source endpoint of a message, the source may have been modified by filters or other actions.
- Parameters
message – The message object in question.
- Returns
A string with the source of a message.
-
void helicsMessageGetRawData(helics_message_object message, void *data, int maxMessageLength, int *actualSize, helics_error *err)¶
Get the raw data for a message object.
@beginPythonOnly
- Parameters
message – A message object to get the data for. @forcpponly
data – [out] The memory location of the data.
maxMessageLength – The maximum size of information that data can hold.
actualSize – [out] The actual length of data copied to data.
err – [inout] A pointer to an error object for catching errors. @endforcpponly
- Returns
Raw string data. @endPythonOnly
-
int helicsMessageGetRawDataSize(helics_message_object message)¶
Get the size of the data payload in bytes.
- Parameters
message – The message object in question.
- Returns
The size of the data payload.
-
const char *helicsMessageGetSource(helics_message_object message)¶
Get the source endpoint of a message.
- Parameters
message – The message object in question.
- Returns
A string with the source endpoint.
-
const char *helicsMessageGetString(helics_message_object message)¶
Get the payload of a message as a string.
- Parameters
message – The message object in question.
- Returns
A string representing the payload of a message.
-
helics_time helicsMessageGetTime(helics_message_object message)¶
Get the helics time associated with a message.
- Parameters
message – The message object in question.
- Returns
The time associated with a message.
-
helics_bool helicsMessageIsValid(helics_message_object message)¶
A check if the message contains a valid payload.
- Parameters
message – The message object in question.
- Returns
helics_true if the message contains a payload.
-
void helicsMessageReserve(helics_message_object message, int reserveSize, helics_error *err)¶
Reserve space in a buffer but don’t actually resize.
The message data buffer will be reserved but not resized.
- Parameters
message – The message object in question.
reserveSize – The number of bytes to reserve in the message object. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsMessageSetData(helics_message_object message, const void *data, int inputDataLength, helics_error *err)¶
Set the data payload of a message as raw data.
- Parameters
message – The message object in question.
data – A string containing the message data.
inputDataLength – The length of the data to input. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsMessageSetDestination(helics_message_object message, const char *dst, helics_error *err)¶
Set the destination of a message.
- Parameters
message – The message object in question.
dst – A string containing the new destination. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsMessageSetFlagOption(helics_message_object message, int flag, helics_bool flagValue, helics_error *err)¶
Set a flag on a message.
- Parameters
message – The message object in question.
flag – An index of a flag to set on the message.
flagValue – The desired value of the flag. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsMessageSetMessageID(helics_message_object message, int32_t messageID, helics_error *err)¶
Set the message ID for the message.
Normally this is not needed and the core of HELICS will adjust as needed.
- Parameters
message – The message object in question.
messageID – A new message ID. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsMessageSetOriginalDestination(helics_message_object message, const char *dst, helics_error *err)¶
Set the original destination of a message.
- Parameters
message – The message object in question.
dst – A string containing the new original source. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsMessageSetOriginalSource(helics_message_object message, const char *src, helics_error *err)¶
Set the original source of a message.
- Parameters
message – The message object in question.
src – A string containing the new original source. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsMessageSetSource(helics_message_object message, const char *src, helics_error *err)¶
Set the source of a message.
- Parameters
message – The message object in question.
src – A string containing the source. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsMessageSetString(helics_message_object message, const char *str, helics_error *err)¶
Set the data payload of a message as a string.
- Parameters
message – The message object in question.
str – A string containing the message data. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsMessageSetTime(helics_message_object message, helics_time time, helics_error *err)¶
Set the delivery time for a message.
- Parameters
message – The message object in question.
time – The time the message should be delivered. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void *helicsMessageGetRawDataPointer(helics_message_object message)¶
Get a pointer to the raw data of a message.
- Parameters
message – A message object to get the data for.
- Returns
A pointer to the raw data in memory, the pointer may be NULL if the message is not a valid message.
Warning
doxygenfunction: Cannot find function “helicsMessageSetOrginalSource” in doxygen xml output for project “helics” from directory: /home/docs/checkouts/readthedocs.org/user_builds/helics/checkouts/helics2/build-doxygen/docs/xml
-
void helicsMessageResize(helics_message_object message, int newSize, helics_error *err)¶
Resize the data buffer for a message.
The message data buffer will be resized. There are no guarantees on what is in the buffer in newly allocated space. If the allocated space is not sufficient new allocations will occur.
- Parameters
message – The message object in question.
newSize – The new size in bytes of the buffer. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
Publication¶
-
void helicsPublicationAddTarget(helics_publication pub, const char *target, helics_error *err)¶
Add a named input to the list of targets a publication publishes to.
- Parameters
pub – The publication to add the target for.
target – The name of an input that the data should be sent to. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
const char *helicsPublicationGetInfo(helics_publication pub)¶
Get the data in the info field of an publication.
- Parameters
pub – The publication to query.
- Returns
A string with the info field string.
-
const char *helicsPublicationGetKey(helics_publication pub)¶
Get the key of a publication.
This will be the global key used to identify the publication to the federation.
- Parameters
pub – The publication to query.
- Returns
A void enumeration, helics_ok if everything worked.
-
int helicsPublicationGetOption(helics_publication pub, int option)¶
Get the value of an option for a publication
- Parameters
pub – The publication to query.
option – The value to query see /ref helics_handle_options.
- Returns
A string with the info field string.
-
const char *helicsPublicationGetType(helics_publication pub)¶
Get the type of a publication.
- Parameters
pub – The publication to query.
- Returns
A void enumeration, helics_ok if everything worked.
-
const char *helicsPublicationGetUnits(helics_publication pub)¶
Get the units of a publication.
- Parameters
pub – The publication to query.
- Returns
A void enumeration, helics_ok if everything worked.
-
helics_bool helicsPublicationIsValid(helics_publication pub)¶
Check if a publication is valid.
- Parameters
pub – The publication to check.
- Returns
helics_true if the publication is a valid publication.
-
void helicsPublicationPublishBoolean(helics_publication pub, helics_bool val, helics_error *err)¶
Publish a Boolean Value.
- Parameters
pub – The publication to publish for.
val – The boolean value to publish. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsPublicationPublishChar(helics_publication pub, char val, helics_error *err)¶
Publish a single character.
- Parameters
pub – The publication to publish for.
val – The numerical value to publish. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsPublicationPublishComplex(helics_publication pub, double real, double imag, helics_error *err)¶
Publish a complex value (or pair of values).
- Parameters
pub – The publication to publish for.
real – The real part of a complex number to publish.
imag – The imaginary part of a complex number to publish. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsPublicationPublishDouble(helics_publication pub, double val, helics_error *err)¶
Publish a double floating point value.
- Parameters
pub – The publication to publish for.
val – The numerical value to publish. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsPublicationPublishInteger(helics_publication pub, int64_t val, helics_error *err)¶
Publish an integer value.
- Parameters
pub – The publication to publish for.
val – The numerical value to publish. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsPublicationPublishNamedPoint(helics_publication pub, const char *str, double val, helics_error *err)¶
Publish a named point.
- Parameters
pub – The publication to publish for.
str – A string for the name to publish.
val – A double for the value to publish. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsPublicationPublishRaw(helics_publication pub, const void *data, int inputDataLength, helics_error *err)¶
Publish raw data from a char * and length.
- Parameters
pub – The publication to publish for.
data – A pointer to the raw data.
inputDataLength – The size in bytes of the data to publish. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsPublicationPublishString(helics_publication pub, const char *str, helics_error *err)¶
Publish a string.
- Parameters
pub – The publication to publish for.
str – The string to publish. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsPublicationPublishTime(helics_publication pub, helics_time val, helics_error *err)¶
Publish a time value.
- Parameters
pub – The publication to publish for.
val – The numerical value to publish. @forcpponly
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsPublicationPublishVector(helics_publication pub, const double *vectorInput, int vectorLength, helics_error *err)¶
Publish a vector of doubles.
- Parameters
pub – The publication to publish for.
vectorInput – A pointer to an array of double data. @forcpponly
vectorLength – The number of points to publish.
err – [inout] A pointer to an error object for catching errors. @endforcpponly
-
void helicsPublicationSetInfo(helics_publication pub, const char *info, helics_error *err)¶
Set the data in the info field for a publication.
- Parameters
pub – The publication to set the info field for.
info – The string to set. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsPublicationSetMinimumChange(helics_publication pub, double tolerance, helics_error *err)¶
Set the minimum change detection tolerance.
- Parameters
pub – The publication to modify.
tolerance – The tolerance level for publication, values changing less than this value will not be published. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
-
void helicsPublicationSetOption(helics_publication pub, int option, int val, helics_error *err)¶
Set the value of an option for a publication
- Parameters
pub – The publication to query.
option – Integer code for the option to set /ref helics_handle_options.
val – The value to set the option to. @forcpponly
err – [inout] An error object to fill out in case of an error. @endforcpponly
Query¶
-
const char *helicsQueryBrokerExecute(helics_query query, helics_broker broker, helics_error *err)¶
Execute a query directly on a broker.
The call will block until the query finishes which may require communication or other delays.
- Parameters
query – The query object to use in the query.
broker – The broker to send the query to. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
A pointer to a string. The string will remain valid until the query is freed or executed again. @forcpponly The return will be nullptr if broker or query is an invalid object, the return string will be “#invalid” if the query itself was invalid @endforcpponly
-
const char *helicsQueryCoreExecute(helics_query query, helics_core core, helics_error *err)¶
Execute a query directly on a core.
The call will block until the query finishes which may require communication or other delays.
- Parameters
query – The query object to use in the query.
core – The core to send the query to. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
A pointer to a string. The string will remain valid until the query is freed or executed again. @forcpponly The return will be nullptr if core or query is an invalid object, the return string will be “#invalid” if the query itself was invalid. @endforcpponly
-
const char *helicsQueryExecute(helics_query query, helics_federate fed, helics_error *err)¶
Execute a query.
The call will block until the query finishes which may require communication or other delays.
- Parameters
query – The query object to use in the query.
fed – A federate to send the query through. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
A pointer to a string. The string will remain valid until the query is freed or executed again. @forcpponly The return will be nullptr if fed or query is an invalid object, the return string will be “#invalid” if the query itself was invalid. @endforcpponly
-
void helicsQueryExecuteAsync(helics_query query, helics_federate fed, helics_error *err)¶
Execute a query in a non-blocking call.
- Parameters
query – The query object to use in the query.
fed – A federate to send the query through. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
const char *helicsQueryExecuteComplete(helics_query query, helics_error *err)¶
Complete the return from a query called with /ref helicsExecuteQueryAsync.
The function will block until the query completes /ref isQueryComplete can be called to determine if a query has completed or not.
- Parameters
query – The query object to complete execution of. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
A pointer to a string. The string will remain valid until the query is freed or executed again. @forcpponly The return will be nullptr if query is an invalid object @endforcpponly
-
void helicsQueryFree(helics_query query)¶
Free the memory associated with a query object.
-
helics_bool helicsQueryIsCompleted(helics_query query)¶
Check if an asynchronously executed query has completed.
This function should usually be called after a QueryExecuteAsync function has been called.
- Parameters
query – The query object to check if completed.
- Returns
Will return helics_true if an asynchronous query has completed or a regular query call was made with a result, and false if an asynchronous query has not completed or is invalid
Warning
doxygenfunction: Cannot find function “helicsQueryExecuteCompleted” in doxygen xml output for project “helics” from directory: /home/docs/checkouts/readthedocs.org/user_builds/helics/checkouts/helics2/build-doxygen/docs/xml
-
void helicsQuerySetTarget(helics_query query, const char *target, helics_error *err)¶
Update the target of a query.
@forcpponly
- Parameters
query – The query object to change the target of.
target – the name of the target to query
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
-
void helicsQuerySetQueryString(helics_query query, const char *queryString, helics_error *err)¶
Update the queryString of a query.
- Parameters
query – The query object to change the target of.
queryString – the new queryString @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
Others¶
-
void helicsCleanupLibrary(void)¶
Function to do some housekeeping work.
This runs some cleanup routines and tries to close out any residual thread that haven’t been shutdown yet.
-
void helicsCloseLibrary(void)¶
Call when done using the helics library. This function will ensure the threads are closed properly. If possible this should be the last call before exiting.
-
helics_broker helicsCreateBroker(const char *type, const char *name, const char *initString, helics_error *err)¶
Create a broker object.
- Parameters
type – The type of the broker to create.
name – The name of the broker. It can be a nullptr or empty string to have a name automatically assigned.
initString – An initialization string to send to the core-the format is similar to command line arguments. Typical options include a broker address such as broker=”XSSAF” if this is a subbroker, or the number of federates, or the address. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
A helics_broker object. @forcpponly It will be NULL if there was an error indicated in the err object. @endforcpponly
-
helics_broker helicsCreateBrokerFromArgs(const char *type, const char *name, int argc, const char *const *argv, helics_error *err)¶
Create a core object by passing command line arguments.
- Parameters
type – The type of the core to create.
name – The name of the core. It can be a nullptr or empty string to have a name automatically assigned. @forcpponly
argc – The number of arguments. @endforcpponly
argv – The list of string values from a command line. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
A helics_core object.
-
helics_federate helicsCreateCombinationFederate(const char *fedName, helics_federate_info fi, helics_error *err)¶
Create a combination federate from a federate info object.
Combination federates are both value federates and message federates, objects can be used in all functions that take a helics_federate, helics_message_federate or helics_federate object as an argument
- Parameters
fedName – A string with the name of the federate, can be NULL or an empty string to pull the default name from fi.
fi – The federate info object that contains details on the federate. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
An opaque value federate object nullptr if the object creation failed.
-
helics_federate helicsCreateCombinationFederateFromConfig(const char *configFile, helics_error *err)¶
Create a combination federate from a JSON file or JSON string or TOML file.
Combination federates are both value federates and message federates, objects can be used in all functions that take a helics_federate, helics_message_federate or helics_federate object as an argument
- Parameters
configFile – A JSON file or a JSON string or TOML file that contains setup and configuration information. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
An opaque combination federate object.
-
helics_core helicsCreateCore(const char *type, const char *name, const char *initString, helics_error *err)¶
Create a core object.
- Parameters
type – The type of the core to create.
name – The name of the core. It can be a nullptr or empty string to have a name automatically assigned.
initString – An initialization string to send to the core. The format is similar to command line arguments. Typical options include a broker name, the broker address, the number of federates, etc. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
A helics_core object. @forcpponly If the core is invalid, err will contain the corresponding error message and the returned object will be NULL. @endforcpponly
-
helics_core helicsCreateCoreFromArgs(const char *type, const char *name, int argc, const char *const *argv, helics_error *err)¶
Create a core object by passing command line arguments.
- Parameters
type – The type of the core to create.
name – The name of the core. It can be a nullptr or empty string to have a name automatically assigned. @forcpponly
argc – The number of arguments. @endforcpponly
argv – The list of string values from a command line. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
A helics_core object.
-
helics_federate_info helicsCreateFederateInfo(void)¶
Create a federate info object for specifying federate information when constructing a federate.
- Returns
A helics_federate_info object which is a reference to the created object.
-
helics_federate helicsCreateMessageFederate(const char *fedName, helics_federate_info fi, helics_error *err)¶
Create a message federate from a federate info object.
helics_message_federate objects can be used in all functions that take a helics_message_federate or helics_federate object as an argument.
- Parameters
fedName – The name of the federate to create.
fi – The federate info object that contains details on the federate. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
An opaque message federate object.
-
helics_federate helicsCreateMessageFederateFromConfig(const char *configFile, helics_error *err)¶
Create a message federate from a JSON file or JSON string or TOML file.
helics_message_federate objects can be used in all functions that take a helics_message_federate or helics_federate object as an argument.
- Parameters
configFile – A Config(JSON,TOML) file or a JSON string that contains setup and configuration information. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
An opaque message federate object.
-
helics_query helicsCreateQuery(const char *target, const char *query)¶
Create a query object.
A query object consists of a target and query string.
- Parameters
target – The name of the target to query.
query – The query to make of the target.
-
helics_federate helicsCreateValueFederate(const char *fedName, helics_federate_info fi, helics_error *err)¶
Create a value federate from a federate info object.
helics_federate objects can be used in all functions that take a helics_federate or helics_federate object as an argument.
- Parameters
fedName – The name of the federate to create, can NULL or an empty string to use the default name from fi or an assigned name.
fi – The federate info object that contains details on the federate. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
An opaque value federate object.
-
helics_federate helicsCreateValueFederateFromConfig(const char *configFile, helics_error *err)¶
Create a value federate from a JSON file, JSON string, or TOML file.
helics_federate objects can be used in all functions that take a helics_federate or helics_federate object as an argument.
- Parameters
configFile – A JSON file or a JSON string or TOML file that contains setup and configuration information. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
An opaque value federate object.
-
const char *helicsGetBuildFlags(void)¶
Get the build flags used to compile HELICS.
-
const char *helicsGetCompilerVersion(void)¶
Get the compiler version used to compile HELICS.
-
helics_federate helicsGetFederateByName(const char *fedName, helics_error *err)¶
Get an existing federate object from a core by name.
The federate must have been created by one of the other functions and at least one of the objects referencing the created federate must still be active in the process.
- Parameters
fedName – The name of the federate to retrieve. @forcpponly
err – [inout] An error object that will contain an error code and string if any error occurred during the execution of the function. @endforcpponly
- Returns
NULL if no fed is available by that name otherwise a helics_federate with that name.
-
int helicsGetOptionIndex(const char *val)¶
Get an option index for use in /ref helicsPublicationSetOption, /ref helicsInputSetOption, /ref helicsEndpointSetOption, /ref helicsFilterSetOption, and the corresponding get functions.
- Parameters
val – A string with the option name.
- Returns
An int with the option index or (-1) if not a valid property.
-
int helicsGetPropertyIndex(const char *val)¶
Get a property index for use in /ref helicsFederateInfoSetFlagOption, /ref helicsFederateInfoSetTimeProperty, or /ref helicsFederateInfoSetIntegerProperty
- Parameters
val – A string with the property name.
- Returns
An int with the property code or (-1) if not a valid property.
-
const char *helicsGetVersion(void)¶
Get a version string for HELICS.
-
helics_bool helicsIsCoreTypeAvailable(const char *type)¶
Returns true if core/broker type specified is available in current compilation.
Options include “zmq”, “udp”, “ipc”, “interprocess”, “tcp”, “default”, “mpi”.
- Parameters
type – A string representing a core type.
-
const char *helicsSubscriptionGetKey(helics_input ipt)¶
Get the key of a subscription.
- Returns
A const char with the subscription key.
-
helics_error helicsErrorInitialize(void)¶
Return an initialized error object.
-
void helicsErrorClear(helics_error *err)¶
Clear an error object.
clear an error object