Co-Simulation API Overview

Example Program

The Co-Simulation API: Spindle Valve tutorial demonstrates how to couple the SpindleValve example program and Simcenter STAR-CCM+ in a co-simulation analysis.

API Library

The LibraryLoader.h and LibraryLoader.cpp files included in the SpindleValve example demonstrate how to wrap the API library for dynamic loading.

Header Files

In the online help, you can access an HTML version of the header files under the Files tab.

API Structure and Function Suites

The Co-Simulation API consists of a set of functions that provide an interface for communication between your program and the Simcenter STAR-CCM+ API server. These functions are grouped into function suites.

There are two types of function suite. The first type, which includes the main API Suite, the Factory Suite, and the Properties Suite, provides an interface for your program to call into the Simcenter STAR-CCM+ API server. The second type, which includes the Handler Suite, provides an interface for the Simcenter STAR-CCM+ API server to call back into your program. All function suites are contained within the header file, StarccmplusCosimulationApiV#.h, where # is the API version number.

Each function suite is identified by the API version with which the function suite is released and a unique name. This framework allows versioning by providing function suite definitions for each API version. Each new API version may extend an existing function suite, create a new function suite, or retire an old function suite.

Before you can access the function suites, you make a call into the Co-Simulation API library to get a pointer to the API structure.

API Structure

The API structure, which is contained in StarccmplusCosimulationApiStruct.h, contains pointers to the API library functions that allow your program to:

• verify the API version
• retrieve the Simcenter STAR-CCM+ function suites by API version and name
• specify your handler function suite by API version and name

For details on all the available functions and options, go to the Online Help > Classes > StarccmplusCoSimulationApiStruct page.

Main API Suite

The main function suite, StarccmplusApiSuiteV#, where # is the API version number, contains pointers to the API library functions that allow your program to:

• initialize or terminate the API library
• synchronize the connection to the partner
• set the time-step
• set the coupling time interval (explicit coupling) or the number of inner iterations per exchange (implicit coupling)
• instruct your program to wait for data from Simcenter STAR-CCM+
• notify Simcenter STAR-CCM+ that the mesh or field data are ready for export
• notify Simcenter STAR-CCM+ that the current processing loop is complete
• notify Simcenter STAR-CCM+ of any errors and warnings

For details on all the available functions and options, go to the Online Help > Classes > StarccmplusApiSuiteV8 page.

Factory Suite

The factory suite, StarccmplusFactorySuiteV#, where # is the API version number, contains pointers to the API library functions that allow your program to communicate with, and instantiate objects on, the Simcenter STAR-CCM+ API server. Specifically, this function suite allows you to:

• create physics continua
• create regions and boundaries
• create a co-simulation link
• set up the co-simulation link
• create co-simulation zones
• assign regions and boundaries to co-simulation zones
• provide a mesh
• import/export field data
• get and set certain condition and value information in the API server

For details on all the available functions and options, go to the Online Help > Classes > StarccmplusFactorySuiteV8 page.

Properties Suite

To transfer data between your program and the Simcenter STAR-CCM+ API server, you define intermediate data store structures called properties containers. A properties container has its own ID of type int. API calls that create properties containers return the container ID. Your program must retain container IDs for all future operations that involve the same properties container.

The properties suite, StarccmplusPropertiesSuiteV#, where # is the API version number, contains pointers to the API library functions that allow your program to:

• create a properties container
• fill a properties container
• add or remove properties (integers, strings, arrays, arrays of arrays, etc.) to a properties container
• extract properties from a properties container

For details on all the available functions and options, go to the Online Help > Classes > StarccmplusPropertiesSuiteV8 page.

Handler Suite

The handler suite, StarccmplusHandlerSuiteV#, where # is the API version number, contains pointers to the functions that allow Simcenter STAR-CCM+ to call back into your program.

For details, go to the Online Help > Classes > StarccmplusHandlerSuiteV8 page.

Helper Scripts

The Simcenter STAR-CCM+ installation contains two helper scripts, buildapi and starapi. These scripts allow you to compile and launch the example program, SpindleValve. See Example Program.

You can also use these scripts to compile and launch your own program. However, you are advised to compile and launch your program using your own build system, based on requirements.

For example, on Windows you typically compile your code using Microsoft Visual Studio. This approach does not require you to launch your program from the command line. You compile and launch your program directly from Microsoft Visual Studio. For instructions, see the Spindle Valve example Compiling and Launching the Partner Code Using Windows.

buildapi

The buildapi helper script provides a build system for compiling your program. The script works with the following compilers:

• gcc for C and Intel Fortran 11 on Linux
• Intel C++ Compiler and Intel Fortran Compiler on Windows

Note	The script is tested with the compilers that are used to build Simcenter STAR-CCM+. For information, refer to the Installation Guide, section Certified Platforms for Simcenter STAR-CCM+ 2406.

To use the script to compile your code, use the following command:

• Windows:

  > call "[INTEL_C++_INSTALLDIR]\bin\compilervars.bat" intel64
  > [INSTALLDIR]\star\bin\buildapi.bat [<verbosity>] <executable name> [<source files>]

• Linux:

  % [INSTALLDIR]/star/bin/buildapi [<verbosity>] <executable name> [<source files>]

where:

• [<verbosity>] specifies the verbose mode.
  The available options are:

  • -v for low verbosity
  • -vv for medium verbosity
  • -vvv for high verbosity
• <executable name> specifies the target name of the final executable.
• [<source files>] specifies the source code files or includes source file directories. If you do not specify this argument, the compiler will compile all the files with extension .cpp, .c, or .f, .f90 that are located in the current folder.

Note	If you experience problems running the script, open it in a text editor and check that all required paths are resolved by the environment you are working with.

starapi

The starapi script launches your program and sets the environment that allows your program to load the co-simulation library and launch the Simcenter STAR-CCM+ API server. To launch your program from a command console, use the following command:

• Windows:

  > [INSTALLADIR]\star\bin\starapi.bat [<verbosity>] <executable> [<executable arguments>]

• Linux:

  % [INSTALLDIR]/star/bin/starapi [<verbosity>] <executable> [<executable arguments>]

where:

• [<verbosity>] specifies the verbose mode.
  The available options are:

  • -v for low verbosity
  • -vv for medium verbosity
  • -vvv for high verbosity
• <executable> specifies the executable path and name.
• [<executable arguments>] contains additional parameters required by the partner program.

The API server behaves like any other Simcenter STAR-CCM+ servers, that is, you can connect to the API server from a Simcenter STAR-CCM+ client. Visualizing the API server in a Simcenter STAR-CCM+ client can be useful for debugging purposes. However, make sure that you do not make any changes to the API server through the Simcenter STAR-CCM+ client. Any changes to the API server must come from your program through the Co-Simulation API.

Note	Launching your program from a command console checks out a Simcenter STAR-CCM+ license. For information on how to run a co-simulation between your program and Simcenter STAR-CCM+ using a single license, see Running a Co-Simulation between Partner Code and Simcenter STAR-CCM+.