Running the Client in Batch
Large simulations generally require that you prepare the case on your local machine, then submit the case to a remote machine, or remote cluster, for running. In these cases, you can use the Simcenter STAR-CCM+ batch client that executes a series of commands from a macro file without user interaction.
Batch simulations consist of a batch Java client and an instance of a server. The batch client drivers the server through a pre-defined instruction, ('mesh', 'step', or 'run'), or using a Java macro file that you provide. Batch simulations are typically used on compute clusters where you cannot drive the simulation using an interactive client because the compute cluster schedules the simulation to run at a future time. A batch process must be well-defined and able to execute without any user input after it starts.
Running in batch mode requires that you execute Simcenter STAR-CCM+ from the command line, pass it the name of a macro script that contains all the commands necessary to load a mesh, set properties, run a number of iterations and render images of scenes and/or plots. In this mode, the batch client compiles and runs the script, passing on all the information and instructions to the server. If you do not wish to use a macro, then you can append the -batch command option with mesh, run, or step, and Simcenter STAR-CCM+ executes a corresponding action.
The instructions for recording, editing and running a macro file are found under section, Scripting the Application. Similar macro recording techniques can be used to set up a large job on a small machine that would not normally handle the large job. These batch jobs can also be submitted to batch management systems using additional command line parameters.
A client is always required for including hardcopy image output in a batch simulation run. For details about how hardcopy export works in batch, see Managing Hardcopy Output in Batch.
Connecting an Interactive Client to a Batch Simulation
A batch job can also be accessed while in progress, as multiple clients can connect to the same server. By connecting through an additional client, you can perform interactive tasks such as opening scenes and adjusting solver parameters. You can use the auto save feature to save automatically at the end of a run.
Batch clients retain control of the server they spawn until all actions are complete and all interactive clients are disconnected. A batch client does not close its server until all other clients are disconnected. By default, a modal dialog, Automatic Disconnect, appears in the interactive client that tells you the batch client has completed. You can either disconnect from the server, (and allow the batch simulation to close), or choose to cancel disconnect and stay connected to the server. If you fail to make a choice within 60 s the interactive client is automatically disconnected from the server.
You can deactivate the automatic disconnect behavior using the Auto-Disconnect Batch Simulations option in the Options dialog available from the Tools menu.
Preparing Large Simulation Cases
You can prepare the batch script for a large problem that would not necessarily fit onto your computer. This approach would typically happen if your machine did not have enough memory for a large mesh.
In this scenario, first set up a smaller, similar mesh and record the macro using the smaller mesh. Then edit the script and change the name of the mesh file that is imported to represent the original problem. For example, the code in question may look something like:
getSimulation().getImportManager().importFile(resolvePath("smallMesh.ccm"));Change the file name in quotes in addition to any other changes you were needing to make on that file.
Batch Summary Report
A summary report of a batch simulation can be obtained by providing the following command line option:
-batch-reportThe report in .html format provides details of the system the simulation was run on, as well as system information about the simulation itself including elapsed times. It also contains a copy of the Simcenter STAR-CCM+ console output that was written during the simulation.
When you enter the line command, the report is generated in your default browser.
Error Codes
When a batch job completes,
Simcenter STAR-CCM+ returns known error codes. These codes can be accessed using techniques appropriate to the Operating System. On Linux using the Bash shell, the error code can be accessed from the variable
$?. On Windows, the error code is accessed using the environment variable
%errorlevel%.
| Exit Code | Description |
|---|---|
0
|
No Error |
1
|
Generic Error |
2
|
Usage Error |
4
|
File Error |
8
|
Licensing Error |
16
|
Floating Point Error |
32
|
Non-Recoverable Error |
If more than one error condition is encountered the error codes are accumulated. For example, if a file error and a non-recoverable error is encountered the exit code is "4 + 32 = 36".
On Linux, Simcenter STAR-CCM+ also returns exit codes that are associated with known signals. For example, if Simcenter STAR-CCM+ is terminated by sending SIGTERM—which typically has the value 15—to a server process, the batch Simcenter STAR-CCM+ simulation returns exit code 143 (which is 128 + signal number).
When using parallel simulations the Message Passing Interface (MPI), which is responsible for spawning the server processes, may return a non-zero unrecognized error code if the server processes are terminated. The exit code depends upon the specific MPI being used and also on the operating system.
If a subset of parallel processes exit, MPI may explicitly terminate the remaining processes using a platform-dependent method. For example, on Linux, MPI may send SIGTERM to any remaining processes and therefore their exit codes are 143 (the exit code associated with SIGTERM).