为 Simcenter STAR-CCM+ 协同仿真准备程序

程序通过 Simcenter STAR-CCM+ API 服务器与 Simcenter STAR-CCM+ 耦合，该服务器是表示程序的 Simcenter STAR-CCM+ 模拟。通过协同仿真 API 库设置 Simcenter STAR-CCM+ API 服务器并与之通信。Simcenter STAR-CCM+ API 服务器使用 Simcenter STAR-CCM+ 至 Simcenter STAR-CCM+ 协同仿真与其他 Simcenter STAR-CCM+ 模拟耦合。

要设置 Simcenter STAR-CCM+ API 服务器并与之通信，按照以下步骤准备程序。每个步骤都包含一个使用最新版本 API 的程序示例。

在程序中包括以下某个协同仿真 API 头文件。
请参见标头文件。基于功能套件结构的 API 版本不适用于与 v11.04 之前的 Simcenter STAR-CCM+ 版本耦合。
为了动态加载协同仿真 API 库，还需包括随 SpindleValve 示例程序提供的 LibraryLoader.h 和 LibraryLoader.cpp 文件。
- 如果程序采用 C++ 编写，则可直接使用程序中的 LibraryLoader.h 和 LibraryLoader.cpp 文件。
- 如果程序采用 Fortran 或 C 编写，则可通过 C 包装器使用这些文件。
请参见示例程序和 API 库。

定义指向 API 结构和功能套件的指针：

StarccmplusCoSimulationApiStruct const * apiStruct;
StarccmplusApiSuiteV8 const * apiSuite;
StarccmplusFactorySuiteV8 const * factorySuite;
StarccmplusPropertiesSuiteV8 const * propertiesSuite;

定义 Simcenter STAR-CCM+ 用于回调入程序的 messageHandler 和 fillContainerHandler 回调函数：

void messageHandler(StarccmplusMessageType const msgType, char const* message)
{see SpindleValve program for example message handler};

void fillContainerHandler(int containerIndex, char const* requirement)
{see SpindleValve program for example fill container handler};

StarccmplusHandlerSuiteV8 handlerSuite ={
  messageHandler,  
  fillContainerHandler};

加载协同仿真 API 库。
```
apiLib.load();
```
将指针指向 StarccmplusCoSimulationApiStruct.h 中定义的 API 结构。
```
apiLib.getApiStruct(&apiStruct)
```
确认使用的协同仿真 API 版本是否受支持。
启动的 Simcenter STAR-CCM+ 版本由用户选择，即程序无法使用 API 来加载特定版本的 Simcenter STAR-CCM+。通常，程序将验证用户启动的 Simcenter STAR-CCM+ 版本与使用的 API 版本是否兼容，如果不兼容则发出错误消息。
```
apiStruct->isApiVersionSupported(
  API_VERSION,
  &versionsArray, 
  &versionsArraySize);
  
```
API 将查询 Simcenter STAR-CCM+ 以获取受支持的 API 版本列表，然后对比此列表匹配输入 API_VERSION：
- 如果没有匹配项，则 API 调用返回 1。在这种情况下，除非程序可以处理回退到不同版本的 API，否则无法与此版本的 Simcenter STAR-CCM+ 耦合。
- 如果存在匹配项，则 API 调用返回 0。在这种情况下，程序可与此版本的 Simcenter STAR-CCM+ 耦合。
尽管无法使用 API 加载特定版本的 Simcenter STAR-CCM+，但可以考虑 Simcenter STAR-CCM+ 版本来确定 Simcenter STAR-CCM+ 中的可用功能（例如，确定隐式耦合是否可用）。

将指针指向功能套件。

apiStruct->setExternalCodeFunctions(
  API_VERSION, 
  StarccmplusCoSimulationHandlerSuiteName, 
  &handlerSuite);

apiStruct->getStarccmplusFunctions(
  API_VERSION, 
  StarccmplusCoSimulationApiSuiteName, 
  (void const * *)&apiSuite);

apiStruct->getStarccmplusFunctions(
  API_VERSION,
  StarccmplusCoSimulationFactorySuiteName,
  (void const * *)&factorySuite);

apiStruct->getStarccmplusFunctions(
  API_VERSION, 
  StarccmplusCoSimulationPropertiesSuiteName, 
  (void const * *)&propertiesSuite);

完成这些调用后，可以使用功能套件进行所有后续调用。

初始化库。
```
apiSuite->initialize(argc,argv);
```

设置 Simcenter STAR-CCM+ API 服务器：

在 Simcenter STAR-CCM+ API 服务器上创建物理连续体。需要为连续体指定材料模型和时间离散化模型。

int continuumId = factorySuite->createContinuum(
  "Solid Continuum", 
  StarccmplusSingleComponentSolid, 
  StarccmplusSingleSurfacePolyMesh,
  StarccmplusImplicitUnsteady, 
  propertiesSuite->create());

在 Simcenter STAR-CCM+ API 服务器上创建区域。由于区域要求指定连续体 ID，因此确保先创建物理连续体。

int regionId = factorySuite->createRegion(
  continuumId, 
  "Spindle Ball",
  StarccmplusSurfaceRegion,
  StarccmplusSolidRegion);

创建区域边界。由于是在区域内创建边界，因此确保先创建区域。

int boundaryId = factorySuite->createBoundary(
  regionId, 
  "Spindle Ball Surface",
  StarccmplusWallBoundary);

创建并设置协同仿真链接。在这个阶段，还要指定耦合方案（隐式或显式）。

int coSimulationId = factorySuite->createCoSimulation( 
  "Link 1",
  propertiesSuite->create();

int coSimulationId = factorySuite->setupCoSimulation(
  coSimulationId,
  StarccmplusImplicitCoupling,
  propertiesSuite->create();

创建适当类型（对于表面至表面耦合，类型为表面；对于体积至体积耦合，类型为体积）的协同仿真区域。由于是在协同仿真链接中创建协同仿真区域，因此需要协同仿真链接 ID。
```
int zoneId = factorySuite->createCoSimulationZone(
  coSimulationId, 
  "zoneName",
  StarccmplusSurfaceZone,
  propertiesSuite->create();
```
要将模型零部件（边界或区域）与 Simcenter STAR-CCM+ 耦合，将它分配给协同仿真区域。将耦合边界分配给表面区域，将耦合区域分配给体积区域。
```
factorySuite->addModelPartToZone(
zoneId, 
boundaryId);
```
为 Simcenter STAR-CCM+ API 服务器提供符合 Simcenter STAR-CCM+ 多面体网格格式的网格（请参见多面体网格参考）。要注册网格，需要区域 ID。
```
int meshId = factorySuite->registerOutgoingMesh(
  regionId, 
  StarccmplusSurfacePolyMesh);
```

注册序通过协同仿真区域发送到 Simcenter STAR-CCM+ 的数据场。

int displId = factorySuite->registerOutgoingField(
  zoneId,
  StarccmplusVertexFieldLocation,
  StarccmplusDisplacementSpecification, 
  StarccmplusDisplacements, 
  propertiesSuite->create());

注册程序通过协同仿真区域从 Simcenter STAR-CCM+ 接收的数据场。

int pressureId = factorySuite->registerIncomingField(
  zoneId,
  StarccmplusFaceFieldLocation,
  StarccmplusPressureSpecification,
  StarccmplusPressure,
  propertiesSuite->create());

向 Simcenter STAR-CCM+ 通知网格已准备就绪，可以使用：
```
apiSuite->notifyOutgoingMeshesReady();
```

指定求解器设置并运行循环。包括求解器时间步以及耦合时间（对于显式耦合）或每次交换的内部迭代次数（对于隐式耦合）。

设置求解器时间步。可以指定固定时间步，或者查询 Simcenter STAR-CCM+ 模拟，获取时间步和耦合时间间隔。只能在初始连接协商后查询 Simcenter STAR-CCM+。要检查：

apiSuite->waitForUpdate();

要获取 Simcenter STAR-CCM+ 模拟时间步和耦合频率：

int propId = factorySuite->getConditionValueProperties( 
  coSimulationId,
  StarccmplusPropIdPartnerCouplingParameters);

double timeStep = propertiesSuite->getDouble(
   propId,
   StarccmplusPropNameTimeStep);

apiSuite->setTimeStep(t, timeStep);

指定数据交换频率：


显式循环	隐式循环
指定耦合时间，该时间必须等于或大于求解器目标时间（当前时间 + 时间步）。 `apiSuite->setCouplingTime(couplingTime);`	设置每次交换的内部迭代次数。 `apiSuite->setNumberOfInnerIterationsPerExchange( inner_iterations_per_exchange);`

等待流入场。
```
apiSuite->waitForIncomingFields();
```

如果 waitForIncomingFields 调用的返回值非零，表示发生了数据交换。在这种情况下，检索注册的流入场。

propertiesSuite->addDouble(
  pressureId,"Time",t); 
     
propertiesSuite->fill(pressureId,"FieldValues"); 
     
propertiesSuite->getDoubleArray(
  pressureId, "Pressure", &pressField[0], pressField.size());

求解合作伙伴解并准备用于导出的求解数据。
在每次迭代或时间步处，通知 Simcenter STAR-CCM+ 流出场已准备就绪。
```
apiSuite->notifyOutgoingFieldsReady();
```
在求解循环结束时，通知 Simcenter STAR-CCM+ 时间步完成。
```
apiSuite->notifyTimeStepComplete();
```
重复求解循环，直至完成。

完成后，最终完成协同仿真 API 库。
```
apiSuite->finalize();
```
终止 API 库。
```
apiLib.close();
```