Simcenter STAR-CCM+ Customize Simcenter STAR-CCM+ with a self-made NBM-plugin using NetBeans

What are NetBeans Modules and what can you do with them

A NetBeans module (NBM) is a bundle of Java classes that can be added as extension to your Simcenter STAR-CCM+ installation. Thus it can provide additional functionality to the user interface without exposing the source code to the end-user. The Simcenter STAR-CCM+ APT series tools are usually delivered as NBM-plugins for Simcenter STAR-CCM+.

Create a new NetBeans Project

Your main tool to reproduce this example is the NetBeans IDE. Within NetBeans, click on File > New Project and then select from the categories Java with Ant > NetBeans Modules > Module and click on "Next".

In the following form, you can enter a project name and project location. Click "Next".

Finally, you specify the Code Name Base and then you click "Finish". After a few seconds, the new project will appear at the project tree.

Localize your new project and expand its node. You will notice that there is an additional folder compared to other Java projects that is named "Important Files". The most important files within this folder are described in the following table:

XML Layer	(not yet created) This file can be used to get access to the  Simcenter STAR-CCM+ GUI elements such as the menu, toolbar, or keyboard shortcuts. You will use this file later to change the order of the menu entries.
Module Manifest	This file contains some basic information about your module that are important for its installation and startup. You will use it to control the versioning of your module and to declare your module dependencies so that all the needed libraries are available during runtime.
Build Script	You can use this file in order to automate the steps that are necessary after code development and before publication, such as compiling, creation of the NBM file, signing or JAVA-doc creation.
Project Properties	Contains the project properties that can be modified using this file or right-click on your project in the tree and then select "Properties" from the context menu. You will use this file later to include the STAR-CCM+ API.

Add Simcenter STAR-CCM+ Java Libraries

As one of the first steps, you should add the Simcenter STAR-CCM+ JAVA libraries to your project. The procedure for NBM projects is different from that of classical JAVA projects in NetBeans. Here, you need to add the classpath of every single .jar file to the Project Properties file, which requires a smart way to create the classpath string. You can apply following procedure:

1. Open the Project Properties file and enter following line (use your own STAR-CCM+ installation path):

   platform.build.dir=C\:\\Program Files\\Siemens\\17.02.006-R8\\STAR-CCM+17.02.006-R8\\star\\lib\\java\\platform

2. In Windows, open a console window and enter following command (again, use your own STAR-CCM+ installation path):

   dir /s /b "C:\Program Files\Siemens\17.02.006-R8\STAR-CCM+17.02.006-R8\star\lib\java\platform\*.jar" >> filelist.txt

3. Open the filelist in a text editor (Notepad++ recommended). It should contain the absolute paths to any .jar file below the platform directory (including subdirectories). Now, convert this list into the form you need:
   • If you have Windows, first replace all backslashes "\" with slashes "/"
   • In the first line only, replace the absolute path to the platform directory

     C:/Program Files/Siemens/17.02.006-R8/STAR-CCM+17.02.006-R8/star/lib/java/platform

     with

     cp.extra=${platform.build.dir}

   • Then, replace all other occurrences of

     \r\nC:/Program Files/Siemens/17.02.006-R8/STAR-CCM+17.02.006-R8/star/lib/java/platform

     with

     \:${platform.build.dir}

     Here, "\r" means "return" (not present in text files created in Linux) and "\n" means "new line". This step will essentially remove all line breaks and only a single line remains.
4. Copy the resulting line into the Project Properties file and save it.

Within the Project Properties file, you can also define the deploy directory, in which the NBM file will be created. Also, add parameters here to be used as version numbers of your plugin. Add following lines:

deploy.dir=D:/your/path/to/NBM
build.major.number=2022
build.minor.number=1
build.revision.number=0

Your Project Properties file should now look as follows:

Add your macros

Now, the Simcenter STAR-CCM+ JAVA libraries are included within your project. You can check if they are recognized by adding your first JAVA file to Source Packages > mycustommodule (Right-click > New > Java Class). You can name it "HelloWorld" and replace all the code there with following macro:

package mycustommodule;

import star.common.*;

public class HelloWorld extends StarMacro {
    @Override
    public void execute() {
        getActiveSimulation().println("Hello World");
    }
}

This code would simply print the "Hello World" message into the output log. In this place any other arbitrary Simcenter STAR-CCM+ macro could be used instead. If NetBeans does not complain about missing packages, then the library inclusion was successful and you can proceed with the next steps, otherwise review the classpath string in the Project Properties file.

Add an Action-class

After adding your macro to your NBM project, you have to think about, how you can make a call of the HelloWorld class from within the Simcenter STAR-CCM+ GUI. Usually, when you execute macros, you may use the macro toolbar and use the file browser to select the macro. An NBM-plugin provides the opportunity to create a custom menu or toolbar entry or a custom keyboard shortcut to execute your macro. In order to achieve that, you need an additional piece of code: An extension of the Action-class that controls the appearance of your function within the Simcenter STAR-CCM+ GUI and makes a call of your macro. Following classes are available:

LocalizedCallableSystemAction	Action can be performed without a present simulation
SimulationAction	Action requires a present simulation and can be executed even during a running simulation
ActiveSimulationAction	Action requires a present simulation but cannot be executed during a running simulation

It depends on the type of macro whether at least one simulation must be loaded, or the macro can also be executed during a simulation run. The "Hello World" macro can also be played during a simulation run without any problems and is therefore of type "SimulationAction".

Create a new Java class with the name "MyAction" and replace the default code by following:

package mycustommodule;

import org.openide.awt.*;
import star.common.StarScript;
import star.coremodule.actions.SimulationAction;
import star.locale.annotation.StarAction;

// Apply action annotations
@StarAction(display = "Hello World", hint = "Displays Hello World Message")
@ActionID(id = "mycustommodule.MyAction", category = "MyModule")
@ActionRegistration(displayName = "Hello World", lazy = false)
@ActionReferences(value = {
    @ActionReference(path = "Toolbars/HelloWorld", position = 1),
    @ActionReference(path = "Shortcuts", name = "D-Q"),
    @ActionReference(path = "Menu/MyModule", position = 1)})

// Extend the SimulationAction class
public class MyAction extends SimulationAction {
    private static final String ICON = "mycustommodule/icons/helloworld.png";
    @Override
    protected String iconResource() {
        return ICON;
    }
    @Override
    public void performAction() {

        // Create a separate thread
        Thread t = new Thread(new Runnable() {
            @Override
            public void run() {

                // Run macro as StarScript
                StarScript sc = new StarScript(getSimulationProcessObject().getSimulation(), new HelloWorld());
                sc.play();
            }
        });
        t.start();
    }
}

Let’s discuss following sections of the above code:

• Action-Annotations: These statements are used to place the action within the STAR-CCM+ GUI. The name description is registered here and references to the action that can optionally be placed within the toolbars, the menu or as a keyboard shortcut. In this example, a new menu entry called "MyModule" will be created and your action "Hello World" will be under this menu. The keyboard shortcut CTRL+Q can be used to execute this action.
• SimulationAction: You will override some default methods of the SimulationAction class in order to personalize it for your action. First, you can add our own icon to this action. You can do that by referencing to an image file in format of 16x16 pixel (larger images will not be scaled down, so don’t make it too large). Save this image file somewhere in your project files below the "src" folder. Second, write the code that shall be executed by your action within the performAction()-method.
• New Thread: A new Thread will be launched for this action so that the STAR-CCM+ GUI remains responsive during the execution of this action.
• StarScript: Within the new Thread, a new instance of your HelloWorld macro is formed and played.

Set the Module Manifest

Finally, you need to add some entries within your module manifest.mf. Add following lines:

OpenIDE-Module-Module-Dependencies: star.coremodule > 16.3

Whenever you update your module, the OpenIDE-Module-Specification-Version number needs to be increased. You could automate this step by make an entry within your build script. The OpenIDE-Module-Module-Dependencies statement will ensure that the necessary libraries are loaded on runtime of your NBM-plugin.

Publish and Install your Module

Now, you can build your project and create the NBM file by selecting the corresponding actions from the context menu of your project:

The final statement in the output log should read as:

BUILD SUCCESSFUL (total time: 21 seconds)

Now, launch Simcenter STAR-CCM+ and install you freshly build NBM file under Tools > Plugins > Downloaded.

After a restart of STAR-CCM+ you will notice a new icon on the toolbar and a new menu entry, that will become active after you open a simulation file.

Advanced Settings: XML-Layer

You may recognize that the positioning of your own module follows an alphabetical order. Whereas you can control the positioning of the single actions within your menu using the "position" attribute in the @ActionReference annotation, the positioning of the menu itself can be controlled by the XML layer file. If you want to define a custom position for your menu, create a new XML Layer file by right-click your module in the project tree and select New > XML Layer... and click "Finish" to create the file. It will appear also under the "Important Files" node.

Expand the node of the XML Layer file and also the sub-node . Here, you find the elements to which your action was added by using the annotations directly within your Java source code. Those annotations will be used to automatically create the entries of the XML layer file which controls the appearance of items in the GUI. The automatically created entries are not shown in your newly created XML-Layer file, but you can use it to navigate to the generated-layer.xml file in your file system or to add/remove more elements. Right-click on Menu and select "Go to Declaration". This will open the generated-layer.xml file.

Locate the entry for your "MyModule" folder under the Menu and add a position attribute. The intvalue of 300 will essentially place your menu entry to the last position:

    <folder name="Menu">
      <folder name="MyModule">
            <attr name="position" intvalue="300"/>
            <file name="mycustommodule-MyAction.shadow">
                <!--mycustommodule.MyAction-->
                <attr name="originalFile" stringvalue="Actions/MyModule/mycustommodule-MyAction.instance"/>
                <attr intvalue="1" name="position"/>
            </file>
        </folder>
    </folder>

Advanced Settings: Build Script

It’s time to build a new version of your NBM. To reduce the number of clicks during the build process and to automatically increase the version number, you can add some scripts to the Build Script in "Important Files" The build-command "netbeans" and the command to create an NBM file "nbm" will be combined with a self-made revision function into a single procedure which you can name "allstep". The revision function will increase the build.revision.number parameter by 1 and call another function to write the updated version number into the manifest file. Put following code into your Build Script:

<?xml version="1.0" encoding="UTF-8"?>
<project name="mycustommodule" default="allstep" basedir=".">
    <description>Builds, tests, and runs the project mycustommodule.</description>
    <import file="nbproject/build-impl.xml"/>

    <target name="allstep" depends="revision,netbeans,nbm">
        <echo message="Your new NBM file has been created..." />
    </target>

    <target name="revision">
        <propertyfile  file="nbproject/project.properties">
            <entry key="build.revision.number" type="int" operation="+" value="1"/>
        </propertyfile>
        <antcall target="update-global-version"/>
    </target>

    <target name="update-global-version">
        <property file="nbproject/project.properties"/>
        <echo>Building: ${build.major.number}.${build.minor.number}.${build.revision.number}</echo>
        <manifest mode="update" file="manifest.mf">
            <attribute name="OpenIDE-Module-Specification-Version" value="${build.major.number}.${build.minor.number}.${build.revision.number}"/>
        </manifest>
    </target>
</project>

To execute your own function, you can right-click on the Build Script and select Run Target > allstep. Now your NBM file with a new revision number will be created.

The updated version is then recognized by Simcenter STAR-CCM+ so that you can install the new version. After a restart of Simcenter STAR-CCM+, you will notice that your menu is now placed at the right-end. You can now open a simulation and execute your function by selecting it from the menu, from the toolbar or by hitting CTRL+Q on your keyboard. The output log will print: "Hello World". As reference, you may download the NetBeans project files that are attached to this article. Congratulations to your first own Simcenter STAR-CCM+ plugin!