Simcenter STAR-CCM+ Swiss Simcenter STAR-CCM+ Knife: [7] Command and conquer: How to pass command line parameters to your macros.

Summary

Tool for optimization studies. It is shown how to pass command-line parameters to Simcenter STAR-CCM+ macros. Since one of the parameters is a file, that file could be used to pass additional information to the macro.

Details

Attachments:

WindowsCC.7z (7 KB) LinuxCC.7z (7 KB)

The tools that are labelled as "Swiss Simcenter STAR-CCM+ Knife" could be thought as a set of tools with the following properties:

1. They are used sparsely, from time to time,
2. They can save you much work and save you from difficult situations,
3. They must be used with care,
4. If they are used improperly they can affect negatively your simulation results. 

Much in the spirit of the well-known Swiss penknife

A Java application can accept parameters when launched from the command line. That allows you to pass information to the application that can be used to perform different actions without the need to recompile the code.

When an application is launched, the runtime system passes the command-line arguments to the applications main method using an array of Strings. You can find more info on this subject within this Java tutorial. 

Could this be achieved with Simcenter  STAR-CCM+ macros? To answer this question, look at the analogue of the main method for Simcenter STAR-CCM+ macros: the execute method.

 

As you see, the execute method (a method from the StarMacro abstract class) does not expect any arguments, so the answer would be negative. 

Is it possible to overcome this behaviour? Yes.

The parameters can be transferred to the macro as follows:

• The parameters are transferred to a shell program through the command line.
• The shell program defines environmental variables from the parameters.
• The Simcenter  STAR-CCM+ java macro then picks the parameter values from the environment variables.

The key ingredient in the procedure above is the method getenv from the System java class. 
Look at the attached RunIt.java macro:

The macro reads the content of a file that is not hardcoded in the macro itself but passed through the system environmental variable WORKING_FILE which is read with a call to the System.getenv method.
The call System.getenv() returns the list of all environmental variables as a Map where the map keys are the environment variable names, and the map values are the environment variable values. 
The call System.getenv(String name) returns a string containing the value of the environmental variable called name. 

You can pass also numerical parameters by transforming the string to a number format. Examples:

You still pass these parameters to the shell and define the environmental variables with them. A possible solution in Linux is the attached cc.sh file:
 

#!/bin/bash
# First Argument: Working File
# Second Argument: java macro
# Third Argument: .sim file
# Fourth Argument: output file
export STARCCM_PATH=/root/prog/STAR-CCM+/STAR-CCM+11.02.010/star/bin/
export WORKING_FILE=$1
echo "Running STAR-CCM+"
$STARCCM_PATH"starccm+" -batch $2 $3 > $4 2>&1
echo "End of Run"
 

The file includes some comments telling you that the macro expects four arguments. Those arguments are specified through positional parameters ($1 through $4) that contain the contents of the command line.
For this file to be a proper shell script, change its permissions to be executable, by typing

chmod u+x cc.sh

 

in your shell terminal. And if you want to execute it away from the folder where it is located, include its location within your PATH.
Now, when executing the following command.

 

cc.sh HelloWorld.txt RunIt.java test.sim output.log

The shell defines the environmental variable WORKING_FILE  with the first argument. Then, it launches the simulation that is given by the third argument and executes the macro that is provided by the second argument. The macro picks the file that it needs from the WORKING_FILE environmental variable. Finally, the whole output of the simulation is stored in the file provided by the fourth argument. 

An equivalent shell script for windows is also attached (cc.bat). 

Note that you need to adapt the STARCCM_PATH in the shell scripts to your own system, so the shell can find the path to the starccm+ executable. Another option would be to include that path in your PATH environmental variable.
The expected output of the .sim can be seen in the output.log file which at the end looks like what shown below: 

 

Surely you are wondering: Would this tool overcrowd or corrupt my set of environmental variables?
And the answer is no. The command, when launched, is not executed within the calling shell but in a newly created shell. The changes of your environmental variables affect only that temporary shell and not the original one. Therefore, when the scripts come to end, your set of environmental variables remain intact. 

Note too that since one of the information passed to the macro is a file itself, that file could contain further parameter definitions. 

Finally, if you have reached this point, you deserve a quiz question to show you the potential of this tool. Consider the macro below (valid only from Simcenter STAR-CCM+ v11.06 onwards):

What do you think it happens when making these calls?
 

cc.sh RunIt.java Transmutation.java test.sim output1.log
cc.sh Transmutation.java RunIt.java test.sim output2.log

As you see the Command and Conquer Knife tool allows you, not only to pass parameters to your macros but to pass directly macros to Simcenter STAR-CCM+. Those macros could change the STAR-CCM+ behaviour and perform different actions depending on the macro being called. 

Attached you find Linux and Windows versions containing:

• A test.sim saved in version 7.02
• A RunIt.java macro
• Shell scripts cc.sh/cc.bat
• HelloWorld.txt file

The RunIt.java macro has been successfully tested from v7.02 until v13.02.

See also:
Getting Started: Editing a Java Macro

Other STAR-CCM+ Knife tools:
Swiss Simcenter STAR-CCM+ Knife: [1] Big Sources: How to override equations and fix cell physical values.
Swiss Simcenter  STAR-CCM+ Knife: [2] Taming of the Courant Number: Automatic Time-Step Control
Swiss Simcenter STAR-CCM+ Knife: [3] Ignore box: Robin, Zero Pressure Gradient and Slip Flow boundary conditions
Swiss Simcenter  STAR-CCM+ Knife: [4] Manual cosimulator: How to transfer information across multiple simulations via macro.
Swiss Simcenter STAR-CCM+ Knife: [5] Pixel comparison: Integrate image processing tools in your CFD workflow.
Swiss Simcenter STAR-CCM+ Knife: [6] Streamline rider: Integrate scalar and vector fields along streamlines.
Swiss Simcenter STAR-CCM+ Knife: [8] Schmitt Trigger: Let STAR-CCM+ remember things.