协同仿真 API 概述

以下章节提供有关如何通过 Simcenter STAR-CCM+ 协同仿真 API 将程序与 Simcenter STAR-CCM+ 进行耦合的信息。有关可用 API 函数和选项的详细信息，请参考“协同仿真 API 在线帮助”。可通过选择帮助 > 协同仿真 API，从 Simcenter STAR-CCM+ 界面访问在线帮助。

示例程序

Simcenter STAR-CCM+ 安装附带提供了一个示例 C++ 程序 SpindleValve，它将通过使用最新协同仿真 API 版本与 Simcenter STAR-CCM+ 进行耦合。尝试创建自己的程序之前，建议先研究示例程序。SpindleValve 示例程序位于以下位置：
  • Windows：[INSTALLDIR]\Documents\STAR-CCM+TutorialFiles16.06\tutorials\couplingWithCaeCodes\CoSimAPI_Code
  • Linux：[INSTALLDIR]/Documents/STAR-CCM+TutorialFiles16.06/tutorials/couplingWithCaeCodes/CoSimAPI_Code

协同仿真 API：杆阀教程演示了如何在协同仿真分析中将 SpindleValve 示例程序与 Simcenter STAR-CCM+ 进行耦合。

API 库

协同仿真 API 库位于以下位置：
  • Windows：[INSTALLDIR]\star\lib\[OS]\[COMPILER]\lib\StarccmplusCoSimulationApi.dll
  • Linux：[INSTALLDIR]/star/lib/[OS]/[COMPILER]/lib/StarccmplusCoSimulationApi.so

SpindleValve 示例中附带的 LibraryLoader.h 和 LibraryLoader.cpp 文件将演示如何使用 API 库进行动态加载。

标头文件

对于每个受支持的 API 版本，Simcenter STAR-CCM+ 均提供了一个标头文件，其中包含定义该 API 版本的功能套件。标头文件位于 Simcenter STAR-CCM+ 安装中，地址为：
  • Windows：[INSTALLDIR]\star\include
  • Linux：[INSTALLDIR]/star/include

从在线帮助中，可以在文件选项卡下访问标头文件的 HTML 版本。

API 最新版本对应的标头文件是：
StarccmplusCosimulationApiV8.h 包含定义协同仿真 API v8 的功能套件。

程序仅需要包括此标头文件。系统将自动包括 StarccmplusCosimulationApiStruct.h 和 StarccmplusCosimulationApiConstants.h 文件。
StarccmplusCosimulationApiStruct.h 包含功能套件 API 的主要访问功能。
StarccmplusCosimulationApiConstants.h 包含功能套件 API 使用的常数。
注该文件夹包含与已作废版本的 API 相对应的额外标头文件。程序只能包括一个提供的标头文件。

API 结构和功能套件

协同仿真 API 由一组功能组成，为程序和 Simcenter STAR-CCM+ API 服务器之间的通信提供了一个界面。这些功能按功能套件分组。

有两种类型的功能套件。第一种类型（包括主 API 套件、工厂套件和属性套件）可为程序调用 Simcenter STAR-CCM+ API 服务器提供界面。第二种类型（包括处理程序套件）可为 Simcenter STAR-CCM+ API 服务器回调程序提供界面。所有功能套件均包含在标头文件 StarccmplusCosimulationApiV#.h 中，其中，# 为 API 版本号。

每个功能套件均由发布功能套件的 API 版本和唯一名称加以标识。此架构通过为每个 API 版本提供功能套件，有助于加强版本控制。每个 API 新版本均会扩展现有的功能套件、创建新功能套件或者停用旧功能套件。

在访问功能套件之前，可以调用协同仿真 API 库以获取 API 结构指针。

API 结构
StarccmplusCosimulationApiStruct.h 中的 API 结构包含许多指向 API 库功能的指针，允许程序执行以下操作：
  • 验证 API 版本
  • 按 API 版本和名称检索 Simcenter STAR-CCM+ 功能套件
  • 按 API 版本和名称指定处理程序功能套件
有关所有可用功能和选项的详细信息，转到 Online Help > Classes > StarccmplusCoSimulationApiStruct(在线帮助 > 类 > StarccmplusCoSimulationApiStruct) 页面。
主 API 套件
主功能套件 StarccmplusApiSuiteV#（其中，# 为 API 版本号）包含指向 API 库功能的指针，允许程序执行以下操作：
  • 初始化或终止 API 库
  • 同步与合作伙伴的连接
  • 设置时间步
  • 设置耦合时间间隔（显式耦合）或每个交换的内部迭代次数（隐式耦合）
  • 指示程序等待 Simcenter STAR-CCM+ 中的数据
  • 通知 Simcenter STAR-CCM+ 网格或场数据已准备导出
  • 通知 Simcenter STAR-CCM+ 当前处理循环已完成
  • 通知 Simcenter STAR-CCM+ 任何错误和警告
有关所有可用函数和选项的详细信息，转到在线帮助 > 类 > StarccmplusApiSuiteV8 页。
工厂套件
工厂套件 StarccmplusFactorySuiteV#（其中，# 为 API 版本号）包含许多指向 API 库功能的指针，允许程序与 Simcenter STAR-CCM+ API 服务器进行通信并在其中实例化对象。具体地说，此功能套件允许执行以下操作：
  • 创建物理连续体
  • 创建区域和边界
  • 创建协同仿真链接
  • 设置协同仿真链接
  • 创建协同仿真区域
  • 将区域和边界分配给协同仿真区域
  • 提供网格
  • 导入/导出场数据
  • 在 API 服务器中获取并设置特定条件和值信息
有关所有可用函数和选项的详细信息，转到在线帮助 > 类 > StarccmplusFactorySuiteV8 页。
属性套件
要在程序和 Simcenter STAR-CCM+ API 服务器之间传递数据，可以定义名为属性容器的中间体数据存储结构。属性容器具有其自身的 ID，类型为 int。用于创建属性容器的 API 调用将返回容器 ID。对于所有涉及相同属性容器的未来操作，程序均必须保留容器 ID。
属性套件 StarccmplusPropertiesSuiteV#（其中，# 为 API 版本号）包含许多指向 API 库功能的指针，允许程序执行以下操作：
  • 创建属性容器
  • 填充属性容器
  • 在属性容器中添加或移除属性（整数、字符串、数组、数组的数组等）
  • 从属性容器中提取属性
有关所有可用函数和选项的详细信息，转到在线帮助 > 类 > StarccmplusPropertiesSuiteV8 页。
处理程序套件
处理程序套件 StarccmplusHandlerSuiteV#（其中，# 为 API 版本号）包含许多指向允许 Simcenter STAR-CCM+ 回调至程序等功能的指针。
有关详细信息，转至在线帮助 > 类 > StarccmplusHandlerSuiteV8 页。

辅助脚本

Simcenter STAR-CCM+ 安装包含两个辅助脚本，即 buildapi 和 starapi。这些脚本可用于编译和启动示例程序 SpindleValve。请参见示例程序。

也可以使用这些脚本编译和启动自己的程序。但是，建议根据需要使用自己的构建系统编译和启动程序。

例如，在 Windows 中，通常使用 Microsoft Visual Studio 编译代码。此方法不需要从命令行启动程序。可以直接从 Microsoft Visual Studio 编译和启动程序。有关指导说明，请参见杆阀示例使用 Windows 编译和启动合作伙伴代码。

辅助脚本位于以下位置：
  • Windows：
    • [INSTALLDIR]\star\bin\buildapi.bat
    • [INSTALLDIR]\star\bin\starapi.bat
  • Linux：
    • [INSTALLDIR]/star/bin/buildapi
    • [INSTALLDIR]/star/bin/starapi
buildapi
buildapi 辅助脚本提供了一个用于编译程序的构建系统。该脚本使用以下编译器：
  • gcc for C 和 Intel Fortran 11（对于 Linux）
  • Intel C++ 编译器和 Intel Fortran 编译器（对于 Windows）
注该脚本已使用构建 Simcenter STAR-CCM+ 所用的编译器进行测试。有关信息，请参考安装指南中的 Simcenter STAR-CCM+2406 的认证平台一节。
要使用脚本编译程序，使用以下命令：
  • 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>]
其中：
  • [<verbosity>] 指定详细模式。
    可用选项如下：
    • -v 表示详细级别较低
    • -vv 表示详细级别中等
    • -vvv 表示详细级别较高
  • <executable name> 指定最终可执行文件的目标名称。
  • [<source files>] 指定源程序文件或包括源文件目录。如果未指定此参数，则编译器将编译当前文件夹中扩展名为 .cpp、.c 或 .f、.f90 的所有文件。
注如果运行脚本时遇到问题，则使用文本编辑器打开脚本，并检查所有必需的路径均由正在使用的环境加以解析。
starapi
starapi 脚本将启动程序，并设置环境以允许程序加载协同仿真库且启动 Simcenter STAR-CCM+ API 服务器。要通过命令控制台启动程序，使用以下命令：
  • Windows：
    > [INSTALLADIR]\star\bin\starapi.bat [<verbosity>] <executable> [<executable arguments>]
  • Linux：
    % [INSTALLDIR]/star/bin/starapi [<verbosity>] <executable> [<executable arguments>]
其中：
  • [<verbosity>] 指定详细模式。
    可用选项如下：
    • -v 表示详细级别较低
    • -vv 表示详细级别中等
    • -vvv 表示详细级别较高
  • <executable> 指定可执行路径和名称。
  • [<executable arguments>] 包含合作伙伴程序所需的附加参数。

API 服务器的行为与任何其他 Simcenter STAR-CCM+ 服务器的行为类似，即：可以从 Simcenter STAR-CCM+ 客户端连接到 API 服务器。在 Simcenter STAR-CCM+ 客户端中可视化 API 服务器，这对于调试目的十分有用。但是，确保未通过 Simcenter STAR-CCM+ 客户端对 API 服务器做出任何更改。必须通过协同仿真 API 从程序对 API 服务器做出任何更改。

注通过命令控制台启动程序时，将签出 Simcenter STAR-CCM+ 许可证。有关如何使用单一许可证在程序和 Simcenter STAR-CCM+ 之间运行协同仿真的信息，请参见在合作伙伴程序和 Simcenter STAR-CCM+ 之间运行协同仿真。