Python API reference

Cosimulation configuration. This may end up wrapped in another interface.

Parameters
----------
name :
    Name of the simulation.
components :
    List of components in the simulation.
links :
    List of links connecting component ports.
shared_helics_config :
    Optional shared federate configuration applied to all components.
    Per-component values (name, core_name) are derived automatically.

Component capability declarations for build-time validation.

Parameters
----------
version :
    Capabilities schema version.
broker_config :
    Whether this component supports receiving federate_config in static_inputs.json.
    If True, the component can be used with WiringDiagram.shared_helics_config.

HELICS running config for the full simulation.

Examples
--------
Save to JSON

>>> with open(filename, "w") as f:
...    json.dump(config.model_dump(mode="json"), f)

Run Simulation

`$ helics run --path=filename`

generate_runner_config(wiring_diagram: WiringDiagram, component_types: dict[str, type[ComponentType]], compatibility_checker=_bad_compatability_checker, target_directory='.')

Create HELICS run configuration from wiring diagram and component types.

Parameters
----------
wiring_diagram : WiringDiagram
    Configuration describing components, parameters, and links between them
component_types : Dict[str, Type[ComponentType]]
    Dictionary for the wiring diagram component types
    to Python component types
compatibility_checker: function of two types to a bool
    Each link uses the compatability_checker to ensure the link types are
    compatible.

Returns
-------
RunnerConfig
    Configuration which can be used to run the cosimulation

Raises
------
Can raise any exception from component type initialization

initialize_federates(wiring_diagram: WiringDiagram, component_types: dict[str, type[ComponentType]], compatability_checker, target_directory='.') -> list[Federate]

Initialize all the federates.

Extracts config and sends it to each Component in an initalization step,
then finds all dynamic inputs and outputs and sends input mappings.

Parameters
----------
wiring_diagram
component_types : dictionary of component type names to ComponentType class
compatibility_checker : function from types to bool
    Check if source type is compatible with target_type
target_directory : str | Path = "."
    Directory where all components should be initialized.

Returns
-------
List of `Federate` run configuration

Raises
------
ComponentType classes may return errors on configuration.

Component description for simple ComponentType.

Parameters
----------
directory :
    where code is stored relative to where this is run
execute_function :
    command to execute component
static_inputs :
    List of types for the parameter
dynamic_inputs :
    List of input types. Typically subscriptions.
dynamic_outputs :
    List of output types. Typically publications.
capabilities :
    Component capability declarations for build-time validation.

component_from_json(filepath, type_checker)

Load component description from JSON file and create component type.

Parameters
----------
filepath : str | Path
type_checker : function taking the type and value and returning a boolean

Returns
-------
BasicComponent class

basic_component(comp_desc: ComponentDescription, type_checker)

Create a new component type from component definition data.

Parameters
----------
comp_desc : ComponentDescription
     Simplified component representation usually from a JSON file
type_checker : function taking the type and value and returning a boolean

Returns
-------
BasicComponent(system_configuration.ComponentType) :
     ComponentType from the description

Full HELICS federate configuration.

This is what federates receive in static_inputs.json, containing various HELICS
configuration at the top-level (name, core_type, broker, etc). Subtype this in your
applications for custom configuration.

Parameters
----------
name :
    Federate name (derived from Component.name).
core_type :
    HELICS core type (e.g., "zmq", "tcp", "inproc").
core_name :
    Core name for this federate (derived per-component).
core_init :
    Core initialization string.
broker :
    Broker connection configuration.

Examples
--------
>>> config = HELICSFederateConfig(
...     name="state_estimator",
...     core_type="zmq",
...     broker=HELICSBrokerConfig(port=23404)
... )
>>> config.to_json()
'{"name": "state_estimator", "coreType": "zmq", ...}'

HELICS broker connection parameters.

Parameters
----------
host :
    Broker hostname or IP address.
port :
    Broker port number.
key :
    Broker key for authentication.
auto :
    Whether to automatically configure broker connection.
initstring :
    Additional initialization string for broker connection.

Shared federate settings at the WiringDiagram level.

This contains settings that are shared across all federates in a simulation.
Does NOT include name/core_name (those are per-component). Users
are expected to write this as part of the wiring_diagram.json,
and invidual federates get passed `config.to_federate_config()`.

Parameters
----------
core_type :
    HELICS core type (e.g., "zmq", "tcp", "inproc").
core_init :
    Core initialization string.
broker :
    Broker connection configuration.

Examples
--------
>>> shared = SharedFederateConfig(
...     core_type="zmq",
...     broker=HELICSBrokerConfig(port=23404)
... )
>>> config = shared.to_federate_config("my_federate")
>>> config.name
'my_federate'