STAR-CCM+

Introduction

The STAR-CCM+ block enables integrating STAR-CCM+ simulation projects into a workflow. The block maps design parameters, boundary conditions, and other simulation properties to its input and output ports. When this block starts, it receives values to input ports and runs a CFD analysis in STAR-CCM+ with these values as input parameters, processing your data sequentially or in parallel depending on the number of cores used for the simulation. Calculated values of monitored functions are collected and sent to output ports.

Features of the STAR-CCM+ block include:

When the STAR-CCM+ block executes, it actually launches the STAR-CCM+ application consuming its license, so it must be able to communicate with STAR-CCM+ in order to run. The STAR-CCM+ application starts in the following cases:

  • when you get information from the STAR-CCM+ project (build the parameter tree),
  • when you open the selected project from the block configuration dialog,
  • when actually running the workflow,
  • when running simulations on a remote host (see section Running Simulations on a Remote Host), and
  • when connecting to a remote STAR-CCM+ server (see section Connecting to a Remote STAR-CCM+ Server). In case of any remote execution scenario, the block needs to start STAR-CCM+ on the local host to use it as a client.

Compatibility

To run, the STAR-CCM+ block requires STAR-CCM+ installed. The block was tested with STAR-CCM+ v12.02, STAR-CCM+ v13.06, and STAR-CCM+ 2019.1 on Windows and Linux; other versions are also compatible, but were not actively tested.

Configuration

Usually configuration of a STAR-CCM+ block requires the following steps:

  • Select a STAR-CCM+ project file. For details, see Project File.
  • Build a project tree. More information is given in Project Tree and Structure.
  • Specify the nodes to be mapped to the respective input and output ports. Section Node Properties provides a brief overview of the project tree nodes and their values.
  • Set options (common, simulation, server or solver) to be used in a simulation. Refer to the Options section for a reference.

The configuration steps required to run a simulation on a remote host are detailed in Running Simulations on a Remote Host. A quick guide explaining how to connect to a remote STAR-CCM+ server is provided at Connecting to a Remote STAR-CCM+ Server.

Suppose you have a simulation file with geometry of a model built using STAR-CAD tools. The purpose of your simulation is to figure out how changing initial model parameters may influence the monitored functions. Basic configuration steps for this scenario are listed below.

Project File

To start, click b_browse on the top pane in the block’s configuration dialog. Select a STAR-CCM+ project file (.sim).

../_images/page_blocks_STARCCM_project_file.png

Important

The project must contain all features required to generate a mesh (see section Meshing in the STAR-CCM+ user guide for details). Otherwise the block will be unable to work with the project and will show a warning when you try to load the .sim file.

The path to the selected project file is also stored in the STAR-CCM+ simulation path option and thus can be set on the Options tab.

Project Tree

After you select a project file, click b_build_tree in the Project tree pane to build the tree. The block will parse model structure in the project file and select properties which can be changed or read in the workflow. These properties are:

  • Model geometry — for example, diameter, length, depth and other design parameters of the model built using STAR-CAD tools.
  • Parts — surfaces, curves and other geometry data built in other CAD tools.
  • Boundaries — mass flow rate, total temperature, static pressure, and other boundary conditions.
  • Reference frames — for example, reference frames for rotation and translation.
  • User functions — pressure ratios, axial velocity and other functions defined by the user.
  • Parameters — for example, absolute total pressure and other global parameters.
  • Reports — pressure inlet, mass flow and other monitored functions.
  • Scenes — for example, mesh and geometry scenes vizualising geometry data.
  • Plots — various plots such as residual plots and plots displaying solution data from the simulation.

Collected properties are grouped and shown in the tree in the Project tree pane. Note that the structure of this tree partially resembles the STAR-CCM+ model tree, but it can skip some nodes (usually nonparametric) which cannot be used in a workflow. For a full description of the tree structure created by the block, see section Structure.

../_images/page_blocks_STARCCM_document_tree.png

Note that the STAR-CCM+ block actually launches STAR-CCM+ application when you build the tree, so this configuration step may require specifying the full path to the STAR-CCM+ executable (starccm+.exe in Windows, starccm+ in Linux) using the STAR-CCM+ executable path option. Setting the path is essential under Linux. Under Windows the block will try to determine the path automatically.

In the tree, you can select certain nodes that will be mapped to input and output ports. When you select a node, a new corresponding variable appears in the Variables list. The Ports column in this list shows which ports (input, output, or both) are created for the corresponding tree node.

../_images/page_blocks_STARCCM_document_tree_var.png

Nodes in the lists of scenes and plots are special. They allow exporting geometry or simulation results as images. When you map one of these nodes, an output File port is created. If you set up monitoring for this port, the images will be saved in the project database during a workflow run, so you can display them with a Page viewer in Analyze.

Structure

Generally, the project tree structure is as follows:

  • Geometry — lists geometry parameters of the model built using STAR-CAD tools.
    • model
      • parameter
      • parameter
  • Parts — specifies the path for updated model geometry.
    • model
      • path
  • Boundaries — lists all boundary conditions to be used in the simulation.
    • type
      • value
      • value
  • Reference frames — lists user-defined rotating frames of reference.
    • reference frame
    • reference frame
  • User functions — lists user-defined auxiliary functions required to perform specific operations.
    • user function
    • user function
  • Parameters — lists custom parameters that you can define once and assign to multiple components in your model.
    • parameter
    • parameter
  • Reports — lists numerical values of monitored functions.
    • function
    • function
  • Scenes — a flat list of scenes to visualize the model geometry and simulation data.
    • scene
    • scene
  • Plots — a flat list of plots presented in the simulation.
    • plot
    • plot

For our use-case, three empty nodes (parts, reference frames, and user functions) mean that the model has no updated geometry and no reference frames and user functions are required for the simulation.

Node Properties

Hovering a tree node shows a tooltip with its properties: type, value and read-only state.

Type

Geometry, boundaries, reference frames and reports are usually RealScalar, parts are of StringScalar type, user functions may be of RealVector type, parameters are usually RealScalar or RealVector, scenes and plots are of the File type. When you select a node in the project tree, it is mapped to a port of the corresponding type.

Value

Shows the parameter value saved in the selected project file. Note that shown values, as well as the values that STAR-CCM+ reads from and writes to ports, are always in SI units regardless of their unit properties set in the project file.

Read-only

If you select a read-only node in the project tree, it is always mapped to an output port. Writeable nodes are mapped to input ports by default. Read-only nodes are reports, scenes, and plots.

Note that if you map a read-only node to an input port, a validation warning appears in the Issues pane, for example.

Macros

STAR-CCM+ supports executing Java macros before model geometry is updated or after simulation finishes. To prepare the script, you can use the File ‣ Macro ‣ Start recording… command in STAR-CCM+, or write the code manually. The macro to run is specified in block’s configuration using the STAR-CCM+ macro to run after open and STAR-CCM+ macro to run after simulation options. Note that if you specify an invalid path to the macro file, a warning is shown in the Issues pane. A workflow containing a STAR-CCM+ block with incorrect macro settings will not run.

Additional Run Parameters

You can specify additional STAR-CCM+ run parameters (command line options) using the STAR-CCM+ run parameters port. This port accepts a Dict where keys are option names and values are option values.

See the Command Line Reference section of the STAR-CCM+ User Guide for details on STAR-CCM+ command line options. Note that the following options are not supported: -batch, -m, -np, -host, -port, and -noexit.

Power-on-Demand Licenses

The block supports STAR-CCM+ Power-on-Demand licenses which are designed for pay-as-you-go usage and can have multiple keys with different expiration criteria.

To enable running with a Power-on-Demand license, specify the key you want to use with the STAR-CCM+ Power-on-Demand.License key option. By default, this option is empty, meaning that a Power-on-Demand license is not used.

Additional STAR-CCM+ Power-on-Demand.Server option can be used if you want to connect to a non-default license server.

Remote Execution

The STAR-CCM+ block can run simulations remotely. There are two possible scenarios:

  1. Offload simulation to a remote host with STAR-CCM+ installed. Requires SSH access, see Running Simulations on a Remote Host for details.
  2. Connect to a remote host which runs a STAR-CCM+ server. See Connecting to a Remote STAR-CCM+ Server.

The SSH access scenario is the most common way to securely connect a client (the local host which runs pSeven) and the solver on a remote machine. Its main advantage is that the block starts the STAR-CCM+ server automatically, and the required server is configured using block’s options. The second remote execution scenario is more advanced. It implies running the server with the simulation file loaded before configuring the block. Besides, many STAR-CCM+ parameters are specified at the server command line, so related block options are ignored making the scenario less flexible.

Running Simulations on a Remote Host

The block can run simulations on a remote host via SSH. It establishes an SSH connection and automatically starts a STAR-CCM+ server on a remote machine, then it connects to this server to run simulations.

Requirements for remote execution via SSH are listed below.

General steps to run a simulation on a remote host are:

  1. Load the simulation file to the block. Refer to Project File section for details.
  2. Switch to the Options tab and specify the STAR-CCM+ server parameters necessary to establish a secure SSH connection:
  • Executable path: the path to the STAR-CCM+ executable on the remote host.

  • Hostname: remote hostname or IP address. In some cases it may be necessary to supply the IP address of the remote host instead of using the hostname — this depends on your network settings.

  • SSH Port: port to connect to on the remote host; the default port is 22.

  • Username: the username on the remote host.

  • Private key path: the path to the RSA private key file (for example, ~/.ssh/id_rsa). Note that the key file must not be protected with a password.

    Also note that the key must already be added to the list of authorized keys on the remote host (by default, ~/.ssh/authorized_keys), and the remote host must be in the list of known hosts (~/.ssh/known_hosts) on the local host which runs pSeven.

  1. Test this setup in pSeven in the block’s configuration dialog.
  • Switch to the Configuration tab and click b_build_tree in the Project tree pane.
  • The block should show the parameter tree of the simulation file loaded to the remote server.

If you receive an error when trying to build the parameter tree, switch to the pSeven console for a detailed log to find out the reason (use the log level selector to switch the console output level from the default “Info” to “Debug”).

Connecting to a Remote STAR-CCM+ Server

The block can connect to a STAR-CCM+ server on a remote host and run simulations on the server. In this scenario, the block does not start the server automatically, it has to be already up when pSeven tries to connect.

Requirements for connecting to a remote STAR-CCM+ server are listed below.

  • STAR-CCM+ installation requirements:
    • STAR-CCM+ installed on the host which runs pSeven (the local host). This installation will not run the solver — the block only uses it as a client to connect to the simulation server.
    • STAR-CCM+ installed on the remote host.
    • The version numbers of the local and remote STAR-CCM+ installations must be exactly the same.
    • The remote STAR-CCM+ server has to be already running when pSeven tries to connect.
  • Block configuration requirements:
    • A simulation file should be loaded on the server. Actually all project files should also be stored on the server host. This file is specified in the command line when you start the server. Therefore, the STAR-CCM+ simulation path option that stores the path to the selected simulation file is ignored. Note that block’s STAR-CCM+ Solver.Number of CPU Cores option is also not taken into account as the number of parallel processes to create, if any, is specified when starting the server.
    • Setting the STAR-CCM+ Server.Hostname and STAR-CCM+ Server.Port options. In some cases it may be necessary to supply the IP address of the remote host to the STAR-CCM+ Server.Hostname option instead of using the hostname — this depends on your network settings.
    • Specifying the path to the local STAR-CCM+ with the STAR-CCM+ executable path option. Note that if pSeven is installed on a Windows host, the block should find the local STAR-CCM+ executable automatically using information from the Windows registry. If the local host runs Linux, the STAR-CCM+ executable path option is always required.

General steps to run a simulation on a remote STAR-CCM+ server are:

  1. Start the STAR-CCM+ server on the remote host with your simulation file, for example:

    starccm+ -server -collab -load ~/MySimulation.sim
    

    Note that the -collab option is required when user names on the local and remote hosts are different.

    If you want to use multiple cores for simulation, the server should be started in the parallel mode using the -np option:

    starccm+ -server -collab -np 4 -load ~/MySimulation.sim
    

    The -np option specifies the number of parallel processes to create (4 in the example above).

    Note that when started in parallel, the STAR-CCM+ server may ask for your password because it needs to establish SSH connections between its processes. Input the password for the user who is currently logged in on the remote host.

  2. When the STAR-CCM+ server is up, it prints the hostname and port, for example:

    Server::start -host HOSTNAME:47827
    

    The hostname and port number values should be copied to the respective block’s options mentioned above.

  3. After completing this setup, you can test it in pSeven in the block’s configuration dialog:

  • Switch to the Configuration tab and click b_build_tree in the Project tree pane.
  • The block should show the parameter tree of the simulation file loaded on the remote server.

If you receive an error when trying to build the parameter tree, check the following:

  1. The remote STAR-CCM+ server is up, and a simulation file is loaded to the server.

  2. STAR-CCM+ on the local host can establish connection to the remote server. To test this connection:

    • Start the local STAR-CCM+.
    • In the STAR-CCM+ menu select Window ‣ Servers.
    • The Servers panel on the left should show the name of your remote server. If you cannot see it in the list, the server may be down, or there is a network connectivity problem.
    • If you see your server in the list, select it to view its properties. In the server properties table, see File to find the path to the loaded simulation file. If this line is empty, a simulation file was not specified when starting the server.
  3. The block can connect to the local STAR-CCM+. To test the local connectivity, you will have to clear the STAR-CCM+ Server.Hostname option temporarily, otherwise the block will continue to try remote execution. Then, after disabling remote connection:

    • Select a local project file in the block’s configuration dialog.
    • Click b_build_tree in the Project tree pane to build the parameter tree for this local file.

    If you see a correct parameter tree, local STAR-CCM+ is working. If you receive an error, try to check your STAR-CCM+ installation or to set the STAR-CCM+ executable path option. Note that if the block does find the local STAR-CCM+ installation automatically, this option should contain the full path to the executable.

Note

In the remote execution mode, the additional run parameters sent to the STAR-CCM+ run parameters port are interpreted by the local STAR-CCM+ process.

Options


Error handling behavior

The action to perform if the block encounters an error.

Value:stop workflow, output defaults and signal, output signal only
Default:stop workflow

When set to stop workflow, the block simply reports an error and the workflow interrupts.

If set to output defaults and signal, the block suppresses the error. In this case, output ports send values assigned to them (the defaults), and the done port outputs a False value (the signal). Note that the block automatically assigns values to output ports that are created when you select document tree nodes. The values are:

The output signal only behavior means to output only the False value to done; nothing is output to other ports.

STAR-CCM+ executable path

Full path to the STAR-CCM+ executable: starccm+.exe (Windows) or starccm+ (Linux).

Value:path string
Default:empty string

Set the path to the STAR-CCM+ executable (for local runs).

Setting the path is required under Linux.

The file is at: STAR-CCM+_installation_directory/XX.XX.XXX-XX/STAR-CCM+XX.XX.XXX-XX/star/bin/starccm+ where XX.XX.XXX-XX is the STAR-CCM+ version number.

This option is not required under Windows: when empty (default), the block will try to determine the path automatically.

STAR-CCM+ macro to run after open

Path to the STAR-CCM+ Java macro file to execute after opening the STAR-CCM+ project.

Value:path string
Default:empty string (do not run any script before simulation)

The block can run additional project scripts before and after the simulation run in STAR-CCM+. This option specifies the script that runs after opening the project but before the geometry is updated.

STAR-CCM+ macro to run after simulation

Path to the STAR-CCM+ Java macro file to execute after simulation finishes.

Value:path string
Default:empty string (do not run any script after simulation)

The block can run additional project scripts before and after the simulation run in STAR-CCM+. This option specifies the script that runs after simulation finishes but before reading values of output parameters.

STAR-CCM+ Power-on-Demand.License key

Enables running with a Power-on-Demand license and specifies the license key.

Value:string
Default:empty string (do not use a Power-on-Demand license)

This option configures the block to use a Power-on-Demand license with the specified key. Default (empty) means that a Power-on-Demand license is not used.

STAR-CCM+ Power-on-Demand.Server

Power-on-Demand license server.

Value:string
Default:1999@flex.cd-adapco.com

Specifies the Power-on-Demand license server port and address. By default, uses the CD-Adapco license server.

Note that this is an additional option which should be changed only if you want to connect to a non-default license server. Running with a Power-on-Demand license is enabled by specifying your license key with the STAR-CCM+ Power-on-Demand.License key option.

STAR-CCM+ save simulation

Save the project after each solver run.

Value:True or False
Default:False (do not save changes)

If enabled (True), the block saves all changes done to the project after running the simulation.

STAR-CCM+ Server.Executable path

Full path to the STAR-CCM+ executable (starccm+) on the remote host.

Value:path string
Default:empty string

Set the path to the STAR-CCM+ executable to connect to the solver on the remote host via SSH.

The starccm+ file is at: STAR-CCM+_installation_directory/XX.XX.XXX-XX/STAR-CCM+XX.XX.XXX-XX/star/bin/starccm+ where XX.XX.XXX-XX is the STAR-CCM+ version number.

STAR-CCM+ Server.Hostname

Hostname of the remote machine or STAR-CCM+ server.

Value:string
Default:empty string

Specify the name or IP address of the computer on which simulation is run. In some cases it may be necessary to provide the IP address instead of using the hostname — this depends on your network settings.

If the field is not empty and STAR-CCM+ Server.Executable path option is specified, the block establishes an SSH connection and automatically starts a STAR-CCM+ server on a remote machine. If only hostname is provided, the block will establish a connection to the remote STAR-CCM+ server. Note that the server should be already running. In this case, the block will ignore the STAR-CCM+ simulation path and STAR-CCM+ Solver.Number of CPU Cores options. If not set, the block will start a server process on the current computer.

STAR-CCM+ Server.Port

Port number of the STAR-CCM+ server.

Value:non-negative integer
Default:47827

Specify the port number that the server process is listening on.

STAR-CCM+ Server.Private key path

Path to the RSA private key file.

Value:string
Default:empty string

Specify the path to the RSA private key file (for example: $HOME/.ssh/id_rsa). Note that the private key file must not be protected with a password.

STAR-CCM+ Server.SSH port

Port to connect to on the remote host.

Value:non-negative integer
Default:22

Specify the port number to establish an SSH connection.

STAR-CCM+ Server.Username

Username on the remote host.

Value:string
Default:empty string

Specify a username on the remote host to establish an SSH connection.

STAR-CCM+ simulation path

Full path to the STAR-CCM+ simulation file.

Value:path string
Default:empty string (no file is selected)

Stores the path to the selected simulation file (.sim). Can also be used to set the path instead of selecting a STAR-CCM+ simulation file on the Configuration tab. If you run a simulation using a remote STAR-CCM+ server, the path to a simulation file is ignored since the block uses the simulation loaded to the remote server.

STAR-CCM+ simulation timeout

Maximum allowed simulation run time in seconds.

Value:non-negative integer
Default:0 (unlimited)

Maximum time that can be spent for a single simulation run. Default (0) means that there is no limit. If another value is set, the block raises an error when the timeout is exceeded. This error is handled according to the Error handling behavior setting.

STAR-CCM+ Solver.Maximum iterations

The maximum number of solver iterations.

Value:non-negative integer
Default:0

Sets the limit for the number of solver iterations. Default (0) means that the value from STAR-CCM+ simulation settings will be applied.

STAR-CCM+ Solver.Number of CPU Cores

Number of CPU cores used by the STAR-CCM+ solver.

Value:positive integer
Default:1

If you run the simulation on a remote STAR-CCM+ server, this option is ignored, and the number of cores to use should be specified in the command line which starts the remote STAR-CCM+ server.

STAR-CCM+ Turbo.Path to data

Path to a .trbw file with STAR-CCM+ TurboWizard data.

Value:path string
Default:empty string (no file is selected)

Sets the path to the TurboWizard (.trbw) file used for turbomachinery simulations. Note that if you run such a simulation remotely, the .trbw file specified in block’s configuration on a local machine should contain correct paths to the files with geometry data located on the remote server.

STAR-CCM+ wait timeout

Time in seconds to wait for the STAR-CCM+ application to become available in case it is currently used by another STAR-CCM+ block.

Value:non-negative integer
Default:300

Several STAR-CCM+ blocks in a workflow can start simultaneously — this is typically the case when there is a Composite block (with parallel execution enabled) containing STAR-CCM+ blocks. In this case, only one of the STAR-CCM+ blocks can connect to the STAR-CCM+ application at a time (this is a STAR-CCM+ limitation). Other blocks have to wait until STAR-CCM+ becomes available, and will do so until the timeout is exceeded.

Exceeding the timeout raises an error which always stops the workflow. That is, the timeout error is never suppressed regardless of the Error handling behavior setting. The workflow is not terminated immediately: all blocks that are currently running continue their execution, and the workflow stops after they finish (soft stop).

Note that setting the timeout to 0 will always trigger workflow stop, if a STAR-CCM+ block with zero timeout starts while there is another STAR-CCM+ block running. The running block will be allowed to finish execution in this case, and the workflow will be stopped by the timeout error from the second block.

Visible

Show the STAR-CCM+ application window when running simulation.

Value:True or False
Default:True (show the window)

When True, the STAR-CCM+ application started by the block runs in a visible window. When False, STAR-CCM+ runs in the background without showing a window.

This option affects only the run-time. When you configure the block (build a project tree), STAR-CCM+ is always launched in the background without showing a window.

Known Issues

This section describes certain issues related to using the STAR-CCM+ block.

STAR-CCM+ License on a Remote Host

When you configure the block to run simulation on a remote host over SSH (see Running Simulations on a Remote Host), the remote STAR-CCM+ instance sometimes cannot find the license if ~/.flexlmrc does not exist on the remote host. If this happens, you can generate ~/.flexlmrc by running STAR-CCM+ on the remote host manually as the user which establishes the SSH connection. It is enough to run STAR-CCM+ once, after this the connection will work automatically.