Workshop: Simulation Assistant

• Java macros: simple demonstration• Wizards: high-end Java• Simulation Assistants as an end user: two examples

– Internal Flow– Muffler aero-acoustics

• Simulation Assistants in detail• Edit and enhance an existing Simulation Assistant

– Netbeans– Add a new scene to a Task

Simulation Assistant: Workshop Content

• The Simulation Assistant– A tool to help guide users through STAR-CCM+ setup processes

• Exposed as a side panel• Leverages the power of Java

– A framework for Authors to replicate best practices and simulation workflows

• The Simulation Assistant – Enhances user experience – Ensures repeatability of a process – Enforces consistency of results– Speeds up learning curve– Shortens time to productivity for

• Users new to STAR-CCM+ or to CFD• Sophisticated and industry specific analysis workflows

What is a Simulation Assistant?

• Simulation Assistant provide a visual workflow within STAR-CCM+– A flexible approach allowing a scalable level of sophistication

• Users– Designed to be a simple way of executing simulation steps without

• Knowing STAR-CCM+ UI • Mastering the physics to analyse

• Authors– Designed to be a simple way of executing simulation tasks

without high levels of Java knowledge• Different to macros which are inherently procedural• Use event driven programming

Why Simulation Assistant?

• The Simulation Assistant appears in a new frame on the right hand side of the STAR-CCM+ window

• The workflow is divided up into different steps– Each step may have a number of actions– Actions are used to execute operations within

STAR-CCM+• Single operation – e.g. change a value • Complex operations – e.g. setup a continuum• Swing operations – e.g. pop-up a new panel

The Simulation Assistant

Where can I learn about …?

• Examples– Three example Simulation Assistants are available for users

• Documentation - Help– A dedicated section in the Help coves using and developing

a Simulation Assistant– A tutorial is available showing the route to building the

Internal Flow Assistant

• The Simulation Assistant is loaded from the File menu– Java files that contain the structure of the Simulation Assistant– May be .java or compiled .jar files

Launching a Simulation Assistant

Main Components

Tasks:• The major stages in

your workflow • May be expanded or

collapsed

Steps:• Operations within a task• Typically presented as

bullet points

Actions:• Hyperlinks that

execute a function

Sub-Tasks• May be expanded

or collapsed within a task

Task Layout

Pre & Post-Conditions:• Optional automatic

enabling/ disabling of tasks

• Ensures required actions are completed before moving forward

Images• May be embedded

in text• Can be used to

execute actions

Information Tags• Clickable icons

that expand • May be used to

provide additional information/instructions

Authoring a Simulation Assistant

• The Simulation Assistant framework provides – A structure to execute actions in a logical and consistent manner

• It can be thought of as executing a series of STAR-CCM+ java macros one by one

– A documented API and consistent coding style

• Provided with STAR-CCM+ are– Tutorial– Documentation– Example Assistants– Javadocs– NetBeans template

How do I Write an Assistant

The Structure of a Simulation Assistant

Compiled project .jar

Compiled Assistant bundles all project files in a single file that can be easily distributed

Assistant .java

The top level assistant is a placeholder for subsequent tasks

Task .javaEach task may contain a number of actions as well as sub-tasks

Text/Layout .xhtml

Text defined by XHTML, may be embedded in task or separate file

Stylesheet .cssIf xhtml files are used, the style of text may be defined by a stylesheet

• It is recommended to use the NetBeans IDE for developing Simulation Assistants– It can be downloaded from https://netbeans.org/– The same IDE helps in writing STAR-CCM+ macros

• Once downloaded install the STAR-CCM+ Simulation Assistant template– Go to Tools > Plugins > Downloaded > Add plugins– Point the plugin manager to nbm file available to download through the

Steve portal– Accept the license terms and usage and continue

Step 1 – Setting up an IDE

• Each Simulation Assistant should be a separate NetBeansproject– Go to file > New Project. The STAR-CCM+ template should be seen with

the Simulation Assistant Project

• Next choose the title, name, location and package/class details of your project

Step 2 – Creating a Project

• The final step in creating the Simulation Assistant project is adding theSTAR-CCM+ libraries– If not already present, create a new library by choosing Manage Libraries…

• Use Add JAR/Folder to add all the files in the lib, core, core\locale, modules, modules\ext & modules\locale sub-directories– These can be found in the STAR-CCM+ installation directory under lib/java/platorm

• Important Note:– On Windows it’s recommended to install STAR-CCM+ in the top level of your hard drive or

move the Java libraries from STAR-CCM+ into a separate location– If STAR-CCM+ is installed to the default location you project may not compile due to a bug in

NetBeans

Step 3 – Adding STAR-CCM+ Libraries

• When a simulation assistant project is created, the top level task is automatically created

• The top level assistant.java simply references each of the subsequent tasks – The tasks are added to an ArrayList

Structure of the Top Level Assistant

@StarAssistant(display=“Assistant Name")public final class AssistantClass extends SimulationAssistant {

public AssistantClass() {List<Task> tasks = new ArrayList<Task>();tasks.add(new Task1name());tasks.add(new Task2name ());tasks.add(new Task3name ());tasks.add(new Task4name ());setOutline(tasks);

}}

Name of the assistant displayed in STAR-CCM+

Assistant Tasks

• To create a new task, right click on the assistant package and choose “New > Simulation Assistant Task”

• Choose the name and location of the task• Before creating the task you can also choose whether the xhtml

is embedded in the task or an external file

Creating a Task

• The main function of the task is to provide actions for the user– The actions themselves, generally take the form of snippets of java code used to

perform STAR-CCM+ tasks i.e. sections of java macro– One task may contain many actions– Actions are exposed via XHTML

Structure of a Task

@StarAssistantTask(display = “Task Name",contentFragment = "<ul><li><a href=\"staraction:action\">action name</a></li></ul>",controller = NewTask.NewTaskController.class)

public class TaskName extends Task {

public class NewTaskController extends FunctionTaskController {

public void action() {notifyUser("Example TaskController function.");

}}

}

Name of the task displayed in STAR-CCM+

xhtml fragment displayed in STAR-CCM+

Task class referenced in the top level

java file

Reference to the action, displayed as a link

Individual action

containing code snippet

• May be created and are shown nested in another task– Each subtask is a new java file

• Added to a tasks by creating an ArrayList

Subtasks

List<Task> subTasks = new ArrayList<Task>();subTasks.add(new Task1A());subTasks.add(new Task1B());subTasks.add(new Task1C());setSubtasks(subTasks);

Task

Expanded subtask

Collapsed subtask

• In many instances a client-server object (cso) such as a may be needed across multiple tasks– e.g. I choose a boundary in task 1 and then want to modify it in task 2– To keep track of these hierarchical lookups are used

• To add an object to the lookup list– addToTaskLookup(cso)

• To retrieve objects– lookupObject(class) - returns the first object of that class from list– lookupObjects(class) – returns all objects of that class from list– getLookup() – returns the entire list– removeFromTaskLookup(cso) – removes a cso from the list– clearTaskLookup() – clears the entire list

Using Lookups

• To highlight the area where an action is working on or where the user should input values, it is possible to expand nodes in the tree

• Two methods are available– selectAndExpandNode(ClientServerObject[] csos)

• Selects the associated nodes in the tree and expands when not visible– selectNodeExclusive(ClientServerObject[] csos)

• Selects the associated nodes in the tree and collapses all other branches

Expanding Nodes

• Conditions are available to automatically enable/disable tasks– e.g. Task 1 creates a geometry, task 2 meshes it – Moving onto task 2 before task 1 is complete is clearly not valid

• Use of conditions can– Help to guide users through the workflow– Add a level of safety so that errors aren’t thrown unnecessarily

• Pre-conditions signify when a task is ready to be executed

• Post-conditions signify when it is completed

• When combined with lookups, the conditions may automatically scan the simulation for changes that may satisfy them– Means you can write a Simulation Assistant that recognizes and responds to objects created outside

of itself– e.g. User can do some tasks in a Simulation Assistant, then some tasks manually, then come back to

the Simulation Assistant

Conditions

Conditions in the Assistant

Conditions are displayed in tabs at the top of tasks

When a task has pre-conditions that aren’t met,

they are greyed out

When conditions are met a tick is placed next to it and information on what the object is that satisfies

it

When all conditions in a task are met, the task is

ticked

• It is recommended to put conditions in a separate file so that their class can be easily integrated into more than one task

• The conditions watch lookups for changes so they may evaluate the condition

Creating Conditions

public static synchronized CSOCondition<ConditionType> createCondition() {

CSOCondition<ConditionType> conditionName = new CSOCondition<ConditionType>();

conditionName.setDesc(“Description of how the condition works");

CSOLookupConditionTrigger<ConditionType> conditionNameTrigger = new CSOLookupConditionTrigger<ConditionType>(ConditionType.class);

conditionName.setTriggers(Collections.singleton(conditionNameTrigger));

conditionName.setPredicate(new Predicate<ConditionType>() {Condition}

});

Sets the type of condition, e.g. PhysicsContinuum, CADPart etc

Create the Condition

Description

Create a trigger that monitors the lookup

Sets the trigger to the one above

Sets the predicate (true/false) evaluation

Create the condition that returns true or

false

• Once conditions are created they may be added to tasks– One or more may be added to a single task– To add a conditions use either

• setPostconditions• SetPreconditions

• To add a single condition

• To add multiple conditons, create an array of conditions then add it

Using Conditions

setPostconditions(Collections.singleton(conditionsclass.createConditionmethod ()));

List<Condition<?>> arrayname = new ArrayList<Condition<?>>(); arrayname.add(conditionsclass.createConditionmethod 1()); arrayname.add(conditionsclass.createConditionmethod 2()); setPostconditions(arrayname);

• Simulation assistant text is created using XHTML– XHTML is well formed HTML – May be embedded in the task but this is relatively inflexible, especially for

tasks with multiple actions– Greater flexibility is achieved using an external xhtml file

• To use external xhtml contentFragment = … is replaced with contentPath = “link.xhtml”

• Content style may be controlled via a CSS file– Default “workflowStyle.css” is automatically created

• Simulation assistants also support the use of images and tables embedded in the xhtml

Using XHTML

• For a complete reference, including attributes for the below tags – http://xhtml.com/en/xhtml/reference/

• Start/end a paragraph– <p></p>

• Use a defined style from the CSS– <style></style>

• Bold type– <strong></strong>

• Actions from tasks are referenced by – <a href=“staraction:action”>action</a> – Images may also be used to perform an action with <a href=“staraction:action”><button><img src=….></button></a>

• Images– <img src=xx></img> inserts images, the size may additionally be defined by width=xxx and height=xxx attributes

• Tables– Tables are started/ended by <table></table>– Each row starts and ends with <tr></tr>– For each column, headings are defined by <th></th> and cell data as <td></td>

Useful XHTML Tags

• If you wish to embed additional information into an action, information tags may be used– <information></information>

• A small icon appears in the task where the information is placed– Clicking the icon expands the information

Information tags

• Un-ordered Lists– Presented as bullets– Entire list and each level started and

ended by<ul></ul>• New lines in list started and ended by

<li></li>

• Ordered lists– Each level numbered– Started and ended by <ol></ol>

• New lines in list started and ended by <li></li>

Lists

• Simulation Assistant provide a visual workflow in STAR-CCM+

– A tool to help guide Users through STAR-CCM+ setup processes

– A framework for Authors to replicate best practices and simulation workflows

– Enhances user experience

– Ensures repeatability of a process

– Enforces consistency of results

– Speeds up learning curve

Conclusions

Thank You