View on GitHub

CoSimIO

Small standalone tool for interprocess communication in CoSimulation contexts for coupling and exchanging data between different solvers or other software-tools.

API documentation

Table of Contents

Public interface of CoSimIO
- Hello
- Connect
- ConnectMPI
- Disconnect
- ImportInfo
- ExportInfo
- ImportData
- ExportData
- ImportMesh
- ExportMesh
- Run
- Register
Doxygen documentation

This page contains the API documentation of the CoSimIO. The public interface is documented in detail, the internal documentation with doxygen is currently work in progress.

Public interface of CoSimIO

Hello

The Hello function can be called without establishing a connection beforehand. It is intended for debugging / setting up the integration of CoSimIO. It takes no input and returns an object of CoSimIO::Info (see here), which contains the version info of the CoSimIO. It also prints a short hello message.

Input

None

Returns

Instance of CoSimIO::Info which contains the following:

name	type	description
major_version	int	Major version of CoSimIO
minor_version	int	Minor version of CoSimIO
patch_version	string	Patch version of CoSimIO

Syntax C++

CoSimIO::Info info = CoSimIO::Hello();

Syntax C

CoSimIO_Info = CoSimIO_Hello();

Syntax Python

info = CoSimIO.Hello()

Connect

This function is used to establish a connection between two partners. It is the first function that must be called, other calls (except Hello) require an active connection.

Requirements

Cannot be called when the same connection was established already.

Input

As this function establishes a connection, it also creates the Communication object. Hence it uses the same input as the Communication. See here for the input.

Returns

Instance of CoSimIO::Info which contains the following:

name	type	description
connection_name	string	name of connection, necessary for further calls to CoSimIO
connection_status	int	status of the connection, can be used to check if connecting was successful

Syntax C++

CoSimIO::Info info = CoSimIO::Connect(
    const CoSimIO::Info& I_Settings);

Syntax C

CoSimIO_Info info = CoSimIO_Connect(
    const CoSimIO_Info I_Settings);

Syntax Python

info = CoSimIO.Connect(
    CoSimIO.Info I_Settings)

ConnectMPI

This function is used to establish a connection between two partners in mpi-parallel simulations. It is the first function that must be called, other calls (except Hello) require an active connection. Note that it should be used instead of Connect, not additionally.

Requirements

Cannot be called when the same connection was established already.

Input

As this function establishes a connection, it also creates the Communication object. Hence it uses the same input as the Communication. See here for the input.

Instance of CoSimIO::Info which contains the following:

name	type	required	default	description
Settings required by the Communication

MPI_Comm MPI-communicator (which for maximum performance only contains the ranks that have part of the interface).

Returns

Instance of CoSimIO::Info which contains the following:

name	type	description
connection_name	string	name of connection, necessary for further calls to CoSimIO
connection_status	int	status of the connection, can be used to check if connecting was successful

Syntax C++

CoSimIO::Info info = CoSimIO::ConnectMPI(
    const CoSimIO::Info& I_Settings,
    MPI_Comm ThisMPIComm);

Syntax C

CoSimIO_Info info = CoSimIO_ConnectMPI(
    const CoSimIO_Info I_Settings,
    MPI_Comm ThisMPIComm);

Syntax Python

# convenience function that internally uses MPI_COMM_WORLD
from CoSimIO.mpi import ConnectMPI
info = ConnectMPI(
    CoSimIO.Info I_Settings)

# passing custom MPI_Comm using mpi4py
from mpi4py import MPI
from CoSimIO.mpi.mpi4pyInterface import mpi4pyCommHolder
info = CoSimIO.mpi.ConnectMPI(
    CoSimIO.Info I_Settings,
    mpi4pyCommHolder(MPI.COMM_WORLD))

Disconnect

Calling this function will disconnect a previously established connection.

Requirements

Can only be called with an active connection (i.e. after calling Connect).

Input

Instance of CoSimIO::Info which contains the following:

name	type	required	default	description
connection_name	string	x	-	output of calling `Connect`

Returns

Instance of CoSimIO::Info which contains the following:

name	type	description
connection_status	int	status of the connection, can be used to check if disconnecting was successful

Syntax C++

CoSimIO::Info info = CoSimIO::Disconnect(
    const CoSimIO::Info& I_Info);

Syntax C

CoSimIO_Info info = CoSimIO_Disconnect(
    const CoSimIO_Info I_Info);

Syntax Python

info = CoSimIO.Disconnect(
    CoSimIO.Info I_Info)

ImportInfo

This function is used to import (receive) an object of CoSimIO::Info from the connection partner. The connection partner has to call ExportInfo. It can be used to exchange metadata between the partners.

Requirements

Can only be called with an active connection (i.e. after calling Connect and before calling Disconnect).

Input

Instance of CoSimIO::Info which contains the following:

name	type	required	default	description
connection_name	string	x	-	output of calling `Connect`
identifier	string	x	-	identifier of the data

Returns

Instance of CoSimIO::Info which contains whatever information was specified by the connection partner. Also elapsed_time is specified.

name	type	description
elapsed_time	double	time for IPC (without waiting)

Syntax C++

CoSimIO::Info info = CoSimIO::ImportInfo(
    const CoSimIO::Info& I_Info);

Syntax C

CoSimIO_Info info = CoSimIO_ImportInfo(
    const CoSimIO_Info I_Info);

Syntax Python

info = CoSimIO.ImportInfo(
    CoSimIO.Info I_Info)

ExportInfo

This function is used to export (send) data to the connection partner. The connection partner has to call ImportInfo. It can be used to exchange metadata between the partners.

Requirements

Can only be called with an active connection (i.e. after calling Connect and before calling Disconnect).

Input

Instance of CoSimIO::Info which contains the following:

name	type	required	default	description
connection_name	string	x	-	output of calling `Connect`
identifier	string	x	-	identifier of the data

and other information, as necessary

Returns

Instance of CoSimIO::Info which contains the following:

name	type	description
elapsed_time	double	time for IPC (without waiting)

Syntax C++

CoSimIO::Info info = CoSimIO::ExportInfo(
    const CoSimIO::Info& I_Info);

Syntax C

CoSimIO_Info info = CoSimIO_ExportInfo(
    const CoSimIO_Info I_Info);

Syntax Python

info = CoSimIO.ExportInfo(
    CoSimIO.Info I_Info)

ImportData

This function is used to import (receive) data from the connection partner. The connection partner has to call ExportData.

Requirements

Can only be called with an active connection (i.e. after calling Connect and before calling Disconnect).

Input

Instance of CoSimIO::Info which contains the following:

name	type	required	default	description
connection_name	string	x	-	output of calling `Connect`
identifier	string	x	-	identifier of the data

Vector of data to be exchanged (type depends on language)

Returns

Instance of CoSimIO::Info which contains the following:

name	type	description
elapsed_time	double	time for IPC (without waiting)

Syntax C++

CoSimIO::Info info = CoSimIO::ImportData(
    const CoSimIO::Info& I_Info,
    std::vector<double>& O_Data);

Syntax C

CoSimIO_Info info = CoSimIO_ImportData(
    const CoSimIO_Info I_Info,
    int* O_Size,
    double** O_Data);

Syntax Python

info = CoSimIO.ImportData(
    CoSimIO.Info I_Info,
    CoSimIO.DoubleVector O_Data)

ExportData

This function is used to export (send) data to the connection partner. The connection partner has to call ImportData.

Requirements

Can only be called with an active connection (i.e. after calling Connect and before calling Disconnect).

Input

Instance of CoSimIO::Info which contains the following:

name	type	required	default	description
connection_name	string	x	-	output of calling `Connect`
identifier	string	x	-	identifier of the data

Vector of data to be exchanged (type depends on language)

Returns

Instance of CoSimIO::Info which contains the following:

name	type	description
elapsed_time	double	time for IPC (without waiting)

Syntax C++

CoSimIO::Info info = CoSimIO::ExportData(
    const CoSimIO::Info& I_Info,
    const std::vector<double>& I_Data);

Syntax C

CoSimIO_Info info = CoSimIO_ExportData(
    const CoSimIO_Info I_Info,
    const int I_Size,
    const double* I_Data);

Syntax Python

info = CoSimIO.ExportData(
    CoSimIO.Info I_Info,
    CoSimIO.DoubleVector I_Data)

ImportMesh

This function is used to import (receive) a mesh (in the form of a CoSimIO::ModelPart) from the connection partner. The connection partner has to call ExportMesh.

Requirements

Can only be called with an active connection (i.e. after calling Connect and before calling Disconnect).

Input

Instance of CoSimIO::Info which contains the following:

name	type	required	default	description
connection_name	string	x	-	output of calling `Connect`
identifier	string	x	-	identifier of the mesh

Instance of CoSimIO::ModelPart

Returns

Instance of CoSimIO::Info which contains the following:

name	type	description
elapsed_time	double	time for IPC (without waiting)

Syntax C++

CoSimIO::Info info = CoSimIO::ImportMesh(
    const CoSimIO::Info& I_Info,
    CoSimIO::ModelPart& O_ModelPart);

Syntax C

CoSimIO_Info info = CoSimIO_ImportMesh(
    const CoSimIO_Info I_Info,
    CoSimIO_ModelPart O_ModelPart);

Syntax Python

info = CoSimIO.ImportMesh(
    CoSimIO.Info I_Info,
    CoSimIO.ModelPart O_ModelPart)

Additional information

See documentation of CoSimIO::ModelPart here.

ExportMesh

This function is used to export (send) a mesh (in the form of a CoSimIO::ModelPart) to the connection partner. The connection partner has to call ImportMesh.

Requirements

Can only be called with an active connection (i.e. after calling Connect and before calling Disconnect).

Input

Instance of CoSimIO::Info which contains the following:

name	type	required	default	description
connection_name	string	x	-	output of calling `Connect`
identifier	string	x	-	identifier of the mesh

Instance of CoSimIO::ModelPart

Returns

Instance of CoSimIO::Info which contains the following:

name	type	description
elapsed_time	double	time for IPC (without waiting)

Syntax C++

CoSimIO::Info info = CoSimIO::ExportMesh(
    const CoSimIO::Info& I_Info,
    const CoSimIO::ModelPart& I_ModelPart);

Syntax C

CoSimIO_Info info = CoSimIO_ExportMesh(
    const CoSimIO_Info I_Info,
    const CoSimIO_ModelPart I_ModelPart);

Syntax Python

info = CoSimIO.ExportMesh(
    CoSimIO.Info I_Info,
    CoSimIO.ModelPart I_ModelPart)

Additional information

See documentation of CoSimIO::ModelPart here.

Run

The Run method is only for remote controlled CoSimulation. Here the CoSimulationApplication takes full control of the solver / code. Functions for controlling the solver / code have to be registered before using the Register function.

Requirements

Can only be called with an active connection (i.e. after calling Connect and before calling Disconnect).

Input

Instance of CoSimIO::Info which contains the following:

name	type	required	default	description
connection_name	string	x	-	output of calling `Connect`

Returns

Instance of CoSimIO::Info which contains the following:

name	type	description
currently_nothing

Syntax C++

CoSimIO::Info info = CoSimIO::Run(
    const CoSimIO::Info& I_Info);

Syntax C

CoSimIO_Info info = CoSimIO_Run(
    const CoSimIO_Info I_Info);

Syntax Python

info = CoSimIO.Run(
    CoSimIO.Info I_Info)

Register

This function is used to register the functions that are used to control the solver / code in a remote controlled CoSimulation. It has to be used before calling the Run function.

Requirements

Can only be called with an active connection (i.e. after calling Connect and before calling Disconnect).

Input

Instance of CoSimIO::Info which contains the following:

name	type	required	default	description
connection_name	string	x	-	output of calling `Connect`
function_name	string	x	-	name of function to be registered (see below)

Function pointer to the function that is to be registered

The following functions can be registered:

AdvanceInTime
InitializeSolutionStep
Predict
SolveSolutionStep
FinalizeSolutionStep
OutputSolutionStep
ImportData
ExportData
ImportMesh
ExportMesh

Returns

Instance of CoSimIO::Info which contains the following:

name	type	description
currently_nothing

Syntax C++

CoSimIO::Info info = CoSimIO::Register(
    const CoSimIO::Info& I_Info,
    std::function<Info(const Info&)> I_FunctionPointer);

Syntax C

CoSimIO_Info info = CoSimIO_Register(
    const CoSimIO_Info I_Info,
    CoSimIO_Info (*I_FunctionPointer)(const CoSimIO_Info I_Info));

Syntax Python

info = CoSimIO.Register(
    CoSimIO.Info I_Info,
    python_function I_FunctionPointer)

Doxygen documentation

Work in progress