INTRODUCTION TO

Application Builder

Introduction to Application Builder© 1998–2020 COMSOL
Protected by patents listed on www.comsol.com/patents, and U.S. Patents 7,519,518; 7,596,474; 7,623,991; 8,457,932;
8,954,302; 9,098,106; 9,146,652; 9,323,503; 9,372,673; 9,454,625; 10,019,544; 10,650,177; and 10,776,541. Patents
pending.
This Documentation and the Programs described herein are furnished under the COMSOL Software License
Agreement (www.comsol.com/comsol-license-agreement) and may be used or copied only under the terms of thelicense agreement.
COMSOL, the COMSOL logo, COMSOL Multiphysics, COMSOL Desktop, COMSOL Compiler, COMSOL Server,
and LiveLink are either registered trademarks or trademarks of COMSOL AB. All other trademarks are the propertyof their respective owners, and COMSOL AB and its subsidiaries and products are not affiliated with, endorsed by,sponsored by, or supported by those trademark owners. For a list of such trademark owners, see www.comsol.com/
trademarks.
Version: COMSOL 5.6

Contact Information
Visit the Contact COMSOL page at www.comsol.com/contact to submit general inquiries, contact
Technical Support, or search for an address and phone number. You can also visit the Worldwide
Sales Offices page at www.comsol.com/contact/offices for address and contact information.
If you need to contact Support, an online request form is located at the COMSOL Access page atwww.comsol.com/support/case. Other useful links include:• Support Center: www.comsol.com/support• Product Download: www.comsol.com/product-download• Product Updates: www.comsol.com/support/updates• COMSOL Blog: www.comsol.com/blogs• Discussion Forum: www.comsol.com/community• Events: www.comsol.com/events• COMSOL Video Gallery: www.comsol.com/video• Support Knowledge Base: www.comsol.com/support/knowledgebase
Part number: CM020011

Contents
Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
The Application Builder Desktop Environment . . . . . . . . . . . . . 12
The Application Builder and the Model Builder. . . . . . . . . . . . . 20
Parameters, Variables, and Scope . . . . . . . . . . . . . . . . . . . . . . 21
Running Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Running Applications in COMSOL Multiphysics . . . . . . . . . . 23
Running Applications with COMSOL Server . . . . . . . . . . . . 31
Compiling and Running Standalone Applications . . . . . . . . . 36
Publishing COMSOL Applications . . . . . . . . . . . . . . . . . . . . . 42
Getting Started with the Application Builder . . . . . . . . . . . . . . . 44
Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
The Form Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
The Individual Form Settings Windows . . . . . . . . . . . . . . . . . 51
Local Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Form Editor Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Form Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Editor Tools in the Form Editor . . . . . . . . . . . . . . . . . . . . . . . 61
Button. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Input Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Text Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Data Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101|3

Data Access in the Form Editor . . . . . . . . . . . . . . . . . . . . . . 104
Sketch and Grid Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Copying Between Applications . . . . . . . . . . . . . . . . . . . . . . . 126
Using Forms in the Model Builder . . . . . . . . . . . . . . . . . . . . 127
Inputs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
The Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Menu Bar and Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Ribbon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Events at Startup and Shutdown. . . . . . . . . . . . . . . . . . . . . . 140
Global Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Form and Form Object Events . . . . . . . . . . . . . . . . . . . . . . . 144
Using Local Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Scalar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Array 1D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Array 2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Choice List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Unit Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Graphics Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
The Method Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Converting a Command Sequence to a Method . . . . . . . . 170
Language Elements Window. . . . . . . . . . . . . . . . . . . . . . . . . 175
Editor Tools in the Method Editor . . . . . . . . . . . . . . . . . . . . 176
Data Access in the Method Editor . . . . . . . . . . . . . . . . . . . . 178

4|

Recording Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Checking Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Find and Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Model Expressions Window . . . . . . . . . . . . . . . . . . . . . . . . . 185
Use Shortcut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Syntax Highlighting, Code Folding, and Indentation . . . . . .187
Method Editor Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Ctrl+Space and Tab for Code Completion. . . . . . . . . . . . . 190
Creating Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Local Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Methods with Input and Output Arguments. . . . . . . . . . . .195
Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Stopping a Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
The Model Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Language Element Examples . . . . . . . . . . . . . . . . . . . . . . . . . 199
Running Methods in the Model Builder . . . . . . . . . . . . . . . . 203
Creating Add-Ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Add-In Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Workflow when Creating and Editing Add-Ins . . . . . . . . . . 216
Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Sounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Appendix A — Form Objects . . . . . . . . . . . . . . . . . . . . . . . . . . 221
List of All Form Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Toggle Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Check Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Combo Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229|5Equation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Web Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Progress Bar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Message Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Results Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Form Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Card Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
File Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Information Card Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Array Input. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Radio Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Selection Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
List Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Slider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Knob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Hyperlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Spacer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Appendix B — Copying Between Applications. . . . . . . . . . . . 305
Appendix C — File Handling and File Scheme Syntax . . . . . . 307
File Handling with COMSOL Server . . . . . . . . . . . . . . . . . . 307

6|File Scheme Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
File Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
File Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Appendix D — Keyboard Shortcuts . . . . . . . . . . . . . . . . . . . . . 328
Appendix E — Built-In Method Library . . . . . . . . . . . . . . . . . . 331
Appendix F — Guidelines for Building Applications . . . . . . . . 349
Appendix G — The Application Library Examples . . . . . . . . . 352

|7

8|

Preface
The typical user of a simulation package is someone who holds a PhD or an MSc,
has several years of experience in modeling and simulation, and underwent
thorough training to use the specific package. He or she typically works as ascientist in the R&D department of a big organization or as an academic
researcher. Because the theory of simulation is complicated and the typicalsimulation package presents many options, it is up to the user to employ his or her
expertise to validate the model and the simulation.
This means that a small group of simulation experts is serving a much larger groupof people working in product development, production, or as students studying
physics effects. Simulation models are oftentimes so complicated that the person
who implemented the model is the only one who can safely provide input data to
get useful output. Hence the use of computer modeling and simulation creates abottleneck in product development, production, and education.
In order to make it possible for this small group to service the much larger group,
the Application Builder offers a solution. It enables simulation experts to create an
intuitive and very specific user interface for his or her otherwise general computermodel — a ready-to-use application. The general model can serve as a starting
point for several different applications, with each application presenting the user
with input and output options relevant only to the specific task at hand. The
application can include user documentation, checks for “inputs within bounds”,
and predefined reports at the click of a button.
Creating an application often requires a collaborative effort by experts within theareas of: physics, numerical analysis, programming, user-interface design, andgraphic design.
To a reasonable extent, COMSOL’s Technical Support team can recommend
physics and numerical analysis settings for your application. In addition, the
COMSOL documentation and online resources can be of great help. For
programming and design, the Technical Support team can provide very limited
help. These are areas where your own development efforts are critical.
The Application Builder makes it easy for a team to create well-crafted applications
that avoid accidental user input errors while keeping the focus on relevant output
details.
We at COMSOL are convinced that this is the way to spread the successful use ofsimulation in the world and we are fully committed to helping make this possible.

|9Introduction
A COMSOL application is an intuitive and efficient way of interacting with a
COMSOL Multiphysics model through a highly specialized user interface. This
book gives a quick overview of the Application Builder desktop environment with
examples that show you how to use the Form Editor and the Method Editor.
Reference materials are also included in this book, featuring a list of the built-in
methods and functions that are available. For detailed information on how to use
the Model Builder, see the book Introduction to COMSOL Multiphysics.
If you want to check out an example application before reading this book,open and explore one of the applications from the Application Libraries in
one of the Applications folders. Keep it open while reading this book to
try things out. Only the Applications folders contain applications with userinterfaces. The other folders in the Application Libraries are tutorialmodels with no user interfaces.
The Application Builder is included in the Windows version of COMSOLMultiphysics and accessible from the COMSOL Desktop environment.
COMSOL Multiphysics and its add-on products are used to create an application.
A license for the same add-on products is required to run the application from the
COMSOL Multiphysics or COMSOL Server™ products.
Additional resources, including video tutorials, are available online atwww.comsol.com.

R UNNING A PPLICATIONS WITH COMSOL M ULTIPHYSICSWith a COMSOL Multiphysics license, applications can be run from the
COMSOL Desktop in Windows, macOS, and Linux.

R UNNING C OMPILED A PPLICATIONS
By using COMSOL Compiler™ you can compile your application to an
executable file for Windows, Linux, and macOS. You can freely distribute theexecutable and it can be run without any license file.

R UNNING A PPLICATIONS WITH COMSOL S ERVER
With a COMSOL Server license, a web implementation of an application can be
run in major web browsers on platforms such as Windows, macOS, iOS, Linux,and Android™. In Windows, you can also run COMSOL applications byconnecting to a COMSOL Server with an easy-to-install COMSOL Client,available for download from www.comsol.com. In addition, you can run
COMSOL applications by connecting to a COMSOL Server from your Android™

10 |device via the COMSOL Client for Android™ app on the Google Play™ store.
COMSOL Server does not include the Application Builder, Physics Builder, orModel Builder tools that come with the COMSOL Desktop environment. Any
application created with the Application Builder will automatically work with a
web browser or any client.

G UIDELINES FOR B UILDING A PPLICATIONS
If you are not experienced in building a graphical user interface or programming,
you may want to read “Appendix F — Guidelines for Building Applications” onpage 349.

A DDITIONAL D OCUMENTATION
Additional documentation with information relevant to building applications canbe found in the books: Application Programming Guide, Application Builder
Reference Manual, and Programming Reference Manual.

| 11

The Application Builder Desktop Environment
MODEL BUILDER and APPLICATION BUILDER —Switch between the Model Builder and the Application
Builder by clicking this button.

APPLICATION BUILDER WINDOW —The Application Builder window with theapplication tree.

COMSOL DESKTOP ENVIRONMENT —The COMSOL Desktop environment provides accessto the Application Builder, including the Form andMethod Editors, as well as the Model Builder.

SETTINGS and EDITOR TOOLS WINDOWS — Click any application
tree node or form object to see its associated Settings window.
The Editor Tools window is used to quickly create form objects.

The screenshot above is representative of what you will see when you are working
with the Application Builder. The main components of the Application Builder
desktop environment are:
• Application Builder window and ribbon tab• COMSOL Desktop environment• Form Editor (see page 51)• Method Editor (see page 170)

12 |

T HE A PPLICATION T REE
The application tree consists of thefollowing nodes:• Inputs• Themes• Main Window• Forms• Events• Declarations• Methods• Libraries

The Inputs node contains subnodes that areof the type Application Argument. These canbe used for input arguments to theapplication when starting it from thecommand line of the operating system.
The Themes node has a Settings window
with choices for the desktop color themes,
as well as font, text color, and other settings
that will affect the general appearance of an
application.
The Main Window node represents the main
window of an application and is also the
top-level node for the user interface. It
contains the window layout, the main menu
specification, and an optional ribbon
specification.
The Forms node contains subnodes that areforms or folders containing local forms.
Each form may contain a number of form
objects such as input fields, graphics
objects, and buttons.
The Events node contains subnodes that are
global events. These include all events that are triggered by changes to the various
data entities, such as global parameters or string variables. Global events can also
be associated with the startup and shutdown of the application.
The Declarations node is used to declare global variables, which are used inaddition to the global parameters and variables defined in the model.

| 13

The Methods node contains subnodes that are methods. Methods contain code foractions not included among the standard run commands of the model tree nodes
in the Model Builder. The methods may, for example, execute loops, process
inputs and outputs, and send messages and alerts to the user of the application.
Methods can modify the model object of a running application or the model
object represented by the Model Builder in the current session.
The Libraries node contains images, sounds, and files to be embedded in an MPH
file so that you do not have to distribute them along with the application. In
addition, the Libraries node may contain Java utility class nodes and nodes forexternal Java and C libraries.

14 |T HE F ORM E DITOR
FORM TAB — The Form tab in the ribbon
gives easy access to the Form Editor.

FORM OBJECTS — Each form contains form objects
such as input fields, check boxes, graphics, images,
buttons, and more.

Form Editor WINDOW — The tabbed Form Editor window allows you to move objects around by
dragging. Click an object to edit its settings.

SETTINGS and EDITOR TOOLS WINDOWS —Click any application tree node or form object to see
its associated Settings window. The Editor Tools
window is used to quickly create form objects.

Use the Form Editor for user interface layout by creating forms with form objects
such as input fields, graphics, and buttons.
The main components of the Form Editor are:
• Form ribbon tab• Application Builder window with the application tree
• Form window• Editor Tools window• Settings window| 15

Creating a New FormTo create a new form, right-click the Forms node of the application tree and selectNew Form. You can also click New Form in the ribbon. Creating a new form willautomatically open the Form Wizard with a number of layout templates.
If your application already has a form, for example form1, and you would like toedit it, you can open the Form Editor in either of two ways:• In the application tree, double-click the form1 node.
• In the application tree, right-click the form1 node and select Edit.

You can also add forms that are local to other forms. When applicable, this option
is available as a menu option from the New Form button.

16 |T HE M ETHOD E DITORMETHOD TAB — The Method
tab in the ribbon gives easy access to tools for writing and debugging code.

METHOD WINDOW — The tabbed
Method Window allows you to switch
between editing different methods.

SETTINGS WINDOW — Click any
application tree node to see its associated Settings window.

MODEL EXPRESSIONS, LANGUAGE ELEMENTS, and EDITOR TOOLS WINDOWS — These windows display tools for writing code. The Model Expressions window shows all constants, parameters,
variables, and functions available in the model. The Language Elements window is used to insert templatecode for built-in methods. The Editor Tools window is used to extract code for editing and running model tree nodes.

Use the Method Editor to write methods for actions not covered by the standard
use of the model tree nodes. A method is another name for what is known in otherprogramming languages as a subroutine, function, or procedure.
The main components of the Method Editor are:
• Method ribbon tab• Application Builder window with the application tree
• Method window• Model Expressions, Language Elements, Editor Tools, and Settings

windows (these are stacked together in the figure above)| 17

Creating a New Method
To create a new method, right-click the Methods node in the application tree andselect New Method. You can also click New Method in the ribbon. In the Global
Method dialog box you can change the name of the method.

Creating a new method will automatically open the Method Editor. Methods
created in this way are global methods and accessible from all methods, form
objects, and from the Developer tab in the Model Builder ribbon. By first clicking
a form node you also have the option of creating a Form Method which is local toa form.
A sequence of commands associated with, for example, a button or menu
item can be automatically converted to a new method by clicking Convert
to Method. Open the new method by clicking Go to Method. You can also
create a method that is local to a form or form object by clicking Convert
to Form Method or Convert to Local Method, respectively. These options areshown in the figure below.

If a method already exists, say with the name method1, then you can open the
Method Editor in any of these ways:• In the application tree, double-click the method1 node.

18 |• In the application tree, right-click the method1 node and select Edit.
• Below the command sequence in the Settings window of a form object or an

event, click Go to Method.

A PPLICATION B UILDER P REFERENCES
To access Preferences for the Application Builder, choose Preferences from the Filemenu and select the Application Builder page.

You can configure the COMSOL Desktop environment so that the Application
Builder is displayed in a separate desktop window. Select the check box Use
separate desktop window for Application Builder.
You can use the keyboard shortcuts Ctrl+Shift+M and Ctrl+Shift+A to switch
between the Model Builder and Application Builder, respectively.
You can set an upper limit to the number of open Form Editor or Method Editor
window tabs. Select the check box Maximum number of editors before closing andedit the number (default 15). Keeping this number low can speed up the loadingof applications that contain a large number of forms.

| 19

The Application Builder and the Model Builder
Use the Application Builder to create an application based on a model built with
the Model Builder. The Application Builder provides two important tools forcreating applications: The Form Editor and the Method Editor. In addition, an
application can have a menu bar or a ribbon. The Form Editor includes
drag-and-drop capabilities for user interface components such as input fields,graphics objects, and buttons. The Method Editor is a programming environmentthat allows you to modify the data structures that represent the different parts ofa model. The figures below show the Model Builder and Application Builder
windows.

When creating an application, you typically start from an existing model.
However, you can just as well build an application user interface and theunderlying model simultaneously. You can easily, at any time, switch between the
Model Builder and Application Builder. The model part of an application, as
represented by the model tree, is sometimes called an embedded model.

20 |The tools in the Application Builder can access and manipulate the settings in theembedded model in several ways; For example:• If the model makes use of parameters and variables, you link these directly

to input fields in the application by using the Form Wizard or Editor Tools.
In this way, the user of an application can directly edit the values of theparameters and variables that affect the model. For more information, seepages 61 and 93.
• By using the Form Wizard or Editor Tools, you can include a button in yourapplication that runs a study node and thereby starts the solver. In addition,
you can use this wizard to include graphics, numerical outputs, check boxes,and combo boxes. For more information, see pages 44 and 61.
• The Data Access tool and the Editor Tools window can be used to directly

access low-level settings in the model for use with form objects or inmethods. For more information, see pages 61, 104, and 176.
• By using the Record Code tool, you can record the commands that are

executed when you perform operations within the model tree and its nodes.
These will then be available in a method for further editing. For more
information, see page 180.

Parameters, Variables, and Scope
The model tree may contain both parameters and variables that are used to control
the settings of a model. The figure below shows the model tree of an application
with nodes for both Parameters and Variables.

Parameters are defined under the Global Definitions node in the model tree and areuser-defined constant scalars that are usable throughout the Model Builder. That
is to say, they are “global” in nature. Important uses are:
• Parameterizing geometric dimensions| 21

• Specifying mesh element sizes• Defining parametric sweeps

Variables can be defined in either the Global Definitions node or in the Definitions
subnode of any model Component node. A globally defined variable can be usedthroughout a model, whereas a model component variable can only be used withinthat component. Variables can be used for spatially or time-varying expressions,
including dependent field variables for which you are solving.
In the Model Builder, a parameter or variable is a string with the additional
restriction that its value is a valid model expression. For more information on theuse of parameters and variables in a model, see the book Introduction to
COMSOL Multiphysics.
An application may need additional variables for use in the Form Editor and theMethod Editor. Such variables are declared in the Application Builder under the
Declarations node in the application tree. The figure below shows the application
tree of an application with multiple declarations.

The declared variables in the Application Builder are typed variables, including
scalars, arrays, Booleans, strings, integers, and doubles. Before using a variable,
you have to declare its type.
The fact that these variables are typed means that they can be used directly inmethods without first being converted using one of the built-in methods. This
makes it easier to write code with typed variables than with parameters andvariables representing model expressions. However, there are several tools
available in the Application Builder for converting between the different kinds ofvariables. For more information, see pages 146 and 331. For more information on
typed variables, see the Application Programming Guide.

22 |Running Applications
With a COMSOL Multiphysics license, applications can be run from the
COMSOL Desktop environment. With a COMSOL Server license, applications
can be run in major web browsers on a variety of operating systems and hardware
platforms. In addition, you can run applications by connecting to COMSOL
Server with clients for Windows or Android.
By using COMSOL Compiler™, you can compile your application to an
executable file that can be run in the Windows, Linux, and macOS operating
systems.
The following two sections explain how to run applications in these different
settings. The third section, “Publishing COMSOL Applications” on page 42,
describes your rights to publish applications.

Running Applications in COMSOL Multiphysics
In COMSOL Multiphysics, you run an application using any of these ways:• Click Test Application in the ribbon or in the Quick Access Toolbar.
• Select Run Application in the File menu or in the Quick Access Toolbar.
• Double-click an MPH file icon on the Windows Desktop.
• Select Test in Web Browser in the ribbon.

T ESTING AN A PPLICATION
Test Application is used for quick tests. It opens a separate window with theapplication user interface while keeping the Application Builder desktop
environment running.

While testing an application, you can apply changes to forms, methods, and theembedded model at run time by clicking the Apply Changes button. Not allchanges can be applied at run time, and in such a case, you are prompted to close
the application and click Test Application again.
To preview the layout of a form without running the application, click Preview
Form in the ribbon.

| 23

When Test Application is used, all methods are automatically compiled with thebuilt-in Java compiler. Any syntax errors will generate error messages and theprocess of testing the application will be stopped. To check for syntax errors before
testing an application, click the Check Syntax button in the Method tab.

Check Syntax finds syntax errors by compiling the methods using the built-in Java
compiler. Any syntax errors will, in this case, be displayed in the Errors andWarnings window in the Method Editor. For more information, see “The Method

Editor” on page 170.

R UNNING AN A PPLICATIONRun Application starts the application in the COMSOL Desktop environment.
Select Run Application to use an application for production purposes. For example,

you can run an application that was created by someone else that is password
protected from editing, but not from running.

D OUBLE -C LICKING AN MPH FILE
When you double-click an MPH file icon on the Windows  Desktop, theapplication opens in COMSOL Multiphysics, provided the MPH file extension isassociated with COMSOL Multiphysics. The application may either be opened forediting or for running. You control this behavior from the root node of theapplication tree. The Settings window for this node has a section titled Applicationin which you may select either Edit application or Run application. A change in thissetting will be applied when you save the MPH file.

24 |The option Edit application will open the application in the Application Builder.
The option Run application will open the application in runtime mode for
production purpose use. This option is similar to selecting Run Application in theFile menu with the difference that double-clicking an MPH file will start a new
COMSOL Multiphysics session.
If you have installed the COMSOL Client for Windows, the MPH file extension
may instead be associated with the COMSOL Client, and double-clicking an
MPH file will prompt you to log in to a COMSOL Server installation.

I GNORING L ICENSE E RRORSIn the Settings window for the application tree root node, the check box Ignore
license errors during launch is used to control the behavior with respect to licensed
products when running applications.

When selected, an application can be started even if all required licenses are notavailable. It is still not possible to use the functionality of products for which thelicense is not available. However, you can write methods to create an applicationsuch that the functionality used is dynamically adapted to which types of licenses
are available.

T ESTING AN A PPLICATION IN A W EB B ROWSERTest in Web Browser is used for testing the application in a web browser. Thisfunctionality makes it easy to test the look and feel of the application when it isaccessed from a web browser connected to a COMSOL Server installation.

You can choose which of the installed web browsers you would like the application
to launch in. Test in Web Browser opens a separate browser window with the| 25

application user interface while keeping the Application Builder desktop
environment running.

T EST A PPLICATION VS . T EST IN W EB B ROWSERTest Application launches the application with a user interface based on Microsoft.
NET Framework components, whereas Test in Web Browser launches theapplication with a user interface based on HTML5 components. Test Application

will display the user interface as it would appear when the application is run with
COMSOL Multiphysics or COMSOL Server, provided the COMSOL Client for
Windows is used to connect with the COMSOL Server installation. Test in Web
Browser will display the user interface as it would appear when the application is
run with COMSOL Server, provided a web browser is used to connect with the
COMSOL Server installation.
For testing the appearance and function of an application user interface in web
browsers for macOS, iOS, Linux, and Android™, a COMSOL Server installationis required.
The table below summarizes the different options for running an application.
SERVER SOFTWARE

CLIENT SOFTWARE TOOL OR COMPONENTCOMSOL Multiphysics

Test Application

COMSOL Multiphysics

Test in Web Browser

COMSOL Multiphysics

Run Application

COMSOL Server

COMSOL Client for Windows

COMSOL Server

COMSOL Client for Android

COMSOL Server

Web Browser

N/A

Executable file compiled with COMSOL Compiler

The Server column represents the software components that perform theCPU-heavy computations. The Client column represents the software tool orcomponent used to present the application user interface. In the case of executable
files, all computations are done locally. For more information on compiled
applications, see “Compiling and Running Standalone Applications” on page 36.

S AVING A R UNNING A PPLICATION
When you test an application, it is assigned the name Untitled.mph and is a copyof the original MPH file. This is not the case when running an application.
By default, the user of an application will not be prompted to save changes when
exiting the application. You control this behavior from the root node of theapplication tree. The Settings window for this node has a section titled Application

26 |in which you may select the check box Ask to save application when closing, asshown in the figure below.

As an alternative, you can add a button or menu item with a command to save theapplication. For more information, see page 138.

A PPLICATION L IBRARIES
From the File menu, select Application Libraries to run and explore the example
applications that are included in the COMSOL installation. Many of thescreenshots in this book are taken from these examples.

| 27

You run an application, or open it for editing, by clicking the corresponding
buttons below the Application Libraries tree.

Applications that contain a model, but no additional forms or methods, cannot be
run and only opened for editing. Applications that contain forms and methods arecollected in folders named Applications.
The applications in the Application Libraries are continuously improved andupdated. You can update the Application Libraries by clicking Update COMSOLApplication Libraries.
Additional applications that are not part of the Application Libraries may beavailable from the COMSOL website in the Application Gallery. To find theseapplications, click the Application Gallery button. This will open a browser withthe web page for the Application Gallery.
Each application has an associated thumbnail image that is displayed in the
Application Libraries. In the COMSOL Server web interface, the thumbnail image
is displayed on the Application Library page.
To set the thumbnail image, click the root node of the application tree. The
Settings window has two options for choosing the image: Set from Graphics
Window and Load from File. You can also Clear the image.

28 |The Load from File option allows you to load images in the PNG or JPG fileformats. Choose an image size from 280-by-210 to 1024-by-768 pixels to ensurethat the image displays properly as a thumbnail in COMSOL Multiphysics and
COMSOL Server.

The Set from Graphics Window option automatically creates two thumbnail images:• An image of size 280-by-210 pixels shown in the Settings window of theapplication tree root node and in the Application Libraries.
• An image of size 1024-by-768 used as the default title page image in reports

and in the Application Libraries in COMSOL Server.

| 29

P ASSWORD P ROTECTION
An application can be password protected to manage permissions. You assign
separate passwords for editing and running in the Settings window, accessible byclicking the root node of the application tree in the Application Builder window.
You must have permission to edit an application in order to create passwords forrunning it.

When you open a password-protected MPH file, for editing or running, a dialog
box prompts you for the password:

To remove password protection, create an empty password.
The password protection is used to encrypt all model and application settings,
including methods. However, binary data, such as the finalized geometry
including embedded CAD files, mesh data, and solution data, is not encrypted.

S ECURITY S ETTINGS
When creating an application with the Application Builder, it is important toconsider the security of the computer hosting the application. Both COMSOLMultiphysics and COMSOL Server provide a very similar set of security settingsfor controlling whether or not an application should be allowed to perform
external function calls, contain links to C libraries, run MATLAB functions, accessexternal processes, and more.

30 |The security settings in COMSOL Multiphysics can be found in the Security pagein the Preferences window accessed from the File menu. In COMSOL Server, they
are available in the Preferences page in the COMSOL Server web interface if you
are logged in as an administrator. If you are not sure what security settings to use,
contact your systems administrator.

Running Applications with COMSOL Server
COMSOL applications can be run by connecting to COMSOL Server from a web
browser or a COMSOL Client for Windows. The COMSOL Client for
Windows allows a user to run applications that require a LiveLink™ product for
CAD, as described in Running Applications in the COMSOL Client.
Running applications in a web browser does not require any installation or web
browser plug-ins. Running an application in a web browser supports interactive
graphics in 1D, 2D, and 3D. In a web browser, graphics rendering in 3D is basedon WebGL™ technology, which is included with all major web browsers.

R UNNING A PPLICATIONS IN A W EB B ROWSERUsing a web browser, you can point directly to the computer name and port
number of a COMSOL Server web interface — for example,
http://comsol-server-machine-url.com:2036, assuming that port number
2036 is used by your COMSOL Server installation. You need to provide ausername and password to log in. If you are running COMSOL Server locally, theaddress field will typically be localhost:2036.

| 31

When logged in, the Application Library page displays a list of applications to run.

Click Run in browser to run an application. Applications are run in separate tabs inthe browser.

32 |Limitations When Running Applications in Web Browsers
When you create applications to run in a web browser, make sure you use the gridlayout mode in the Application Builder; See “Sketch and Grid Layout” on page110. This will ensure that the user interface layout adapts to the size and aspectratio of the browser window. For low-resolution displays, make sure to test theuser interface layout in the target platform to check that all form objects are visible.
Applications that contain resizable graphics forms may not fit in low-resolution
displays. In such cases, use graphics with fixed width and height to make sure allform objects fit in the target browser window. Depending on the type of web
browser and the graphics card, there may be restrictions on how many graphics
objects can be used in an application. You can get around such limitations by,instead of using multiple graphics objects, reuse the same graphics object byswitching its source.
When running in a web browser, the LiveLink™ products for CAD software
packages are not supported.
When running COMSOL applications in web browsers for smartphones andcertain tablets, not all functionality is supported. Typical limitations include theability to play sounds or open documents. In addition, file upload and download
may not be supported.
If the application allows the user to make selections, such as clicking on boundaries
to set boundary conditions, running in a web browser is different from running in
COMSOL Multiphysics or the COMSOL Client for Windows. In a web
browser, boundaries are not automatically highlighted when hovering. Instead, it
is required to click once to highlight a boundary. A second click will make theselection. A third click will highlight for deselection and a fourth click will deselect.
The process is similar for domains, edges, and points.
Note that file browsing functionality is slightly different depending on the webbrowser and depending on the version of the web browser. This may impact theuser experience when running an application that has functionality for saving files
to the client computer. For example, the location of the downloads folder can bechanged in the settings of many web browsers. A web browser may also allow theuser to manually specify the download location for each file. Please refer to the
documentation of your target web browsers for details.

R UNNING A PPLICATIONS IN THE COMSOL C LIENTAs an alternative to using a web browser for running applications, the COMSOLClient for Windows can be used to connect to COMSOL Server for runningapplications natively in the Windows operating system. This typically gives bettergraphics performance and supports more sophisticated graphics rendering in 1D,
2D, and 3D. In addition, the COMSOL Client for Windows allows running| 33

applications that require a LiveLink™ product for CAD, provided that the
COMSOL Server you connect to has the required licenses. You can open an
application with the COMSOL Client for Windows in two different ways:• The COMSOL Server web interface will allow

you to choose between running an application
in a web browser or with the COMSOLClient for Windows.
If you try to run an application with the
COMSOL Client in this way, but it is not yet
installed, you will be prompted to download
and install it.

• If you have the COMSOLClient for Windows
already installed, a desktop
shortcut will be available.
You can double-click its
desktop icon and before
you can use the COMSOLClient to run applications,
you will be prompted to log into a COMSOL Server with a valid username
and password. After login, the COMSOL Client displays a COMSOL Server
web interface identical to that seen when logging in from a web browser.

Using the COMSOL Client, applications run as native Windows applications inseparate windows. For example, applications run in the COMSOL Client may
have a Windows ribbon with tabs. When run in a web browser, ribbons are
represented by a toolbar.

34 |In the figure below, the COMSOL Server web interface is shown (top) with anapplication launched in the COMSOL Client for Windows (bottom).

R UNNING COMSOL S ERVER ON M ULTIPLE C OMPUTERS OR A C LUSTERCOMSOL applications can be run on multiple computers or clusters in two mainways:
• By installing COMSOL Server with primary and secondary instances.
• By configuring one of the study nodes in the Model Builder for a particularcluster.

| 35

Primary and Secondary Instances
Running COMSOL Server on multiple computers using primary and secondary
instances allows for more concurrent users and applications than a single computer
instance (or installation). The main COMSOL Server instance is called primary
and the other instances are called secondary. The primary server is used for all
incoming connections — for example, to show the web interface or to run
applications in a web browser or with COMSOL Client. The actual computations
are offloaded to the secondary server computers. This type of installation has amajor benefit: Applications do not need to be custom-built for a particular cluster.
Load balancing is managed automatically by the primary server, which distributes
the work load between the secondary servers. A COMSOL Server installation canconsist of multiple primary and secondary server installations without additional
license requirements. You can perform administrative tasks using the COMSOL
Server web interface without checking out license keys for users runningapplications. License keys are only checked out when running applications.

Configuring a Study Node for Cluster Sweep or Cluster Computing
If you want to utilize a cluster for applications that require large parametric sweeps
or high-performance computing power, then you can configure the Model
Builder study node(s) of an application using the Cluster Sweep and Cluster
Computing options. Note that for building such applications, you will need a
Floating Network License. You can find more information on configuring a study
node for clusters in the books Introduction to COMSOL Multiphysics and the
COMSOL Multiphysics Reference Manual. For running such cluster-enabledapplications, you can use either COMSOL Server or a Floating Network Licenseof COMSOL Multiphysics. Cluster system configurations are available from the
COMSOL Server web interface.
For more information on COMSOL Server, see the COMSOL Server Manual
available with a COMSOL Server installation or fromhttp://www.comsol.com/documentation/COMSOL_ServerManual.pdf.

Compiling and Running Standalone Applications
If you have a license of COMSOL Compiler™, there will be a Compiler button in
the ribbon section Main, as shown below.

36 |Clicking this button will add a Compiler node to the application tree, shown in the
figure below.

The corresponding Settings window is shown below.

C OMPILING A PPLICATIONS
To compile an application, you need to make a few selections in this window.
Specify an output Directory, where the executable files will be saved after
compilation.
The Runtime option can be left at Download for most situations. COMSOL
Runtime contains all the COMSOL Multiphysics software components needed to
run the application as a standalone program. The Runtime setting specifies where
the COMSOL Runtime environment will be stored and affects the behavior when
the compiled application is started for the first time on a computer. If this setting
is Download then the first time a user is starting the compiled application the
COMSOL Runtime environment files will be downloaded (a service provided by
COMSOL). If the COMSOL Runtime environment already exists on thecomputer, with a matching version number, then no download will be performed.
The option Enabled will bundle the COMSOL Runtime files in the executable file.

| 37

Note that with this option, the file size may be several hundred megabytes evenfor smaller applications.
The Platforms settings determine which target-platform executables should be
generated at compilation. The extensions of the executables for the Windows
and Linux operating systems will be .exe and .sh, respectively. For macOS, a.tar archive is created; unpack this archive on macOS to extract the app.
The Icon for Windows lets you specify the desktop icon. The Splash setting lets you
specify a BMP-image file to be displayed at startup.
After compilation, in the Windows operating system, the executable file will beavailable in the output directory, as shown in the figure below.

As a next step, you can, for example, right-click the EXE-file and create a shortcut
that you then place on the Windows desktop.
You can also compile an application from the operating system command line. For
more information, see the COMSOL Multiphysics Reference Manual.

R UNNING C OMPILED A PPLICATIONSWhen running a compiled application, for example, by double-clicking the .exe
file in the Windows operating system, a splash screen is shown and theapplication will start. If the application has the Splash option set to Default, then aneutral-looking built-in splash screen will be shown.

It is recommended that you replace this with your own splash screen.

38 |If this is the first time you are running an application on a particular computer,then, in addition, a click-through agreement and an Initializing Installer progress
window will be displayed. The initialization progress window is shown below.

After a short moment, the COMSOL Runtime Installer window is displayed, as
shown below.

The COMSOL Runtime Installer and its click-through agreement are only shown
once, and the next time you start the same application, it will not be shown. The
click-through agreement and initialization progress window will also not beshown if you run another application on the same computer that was generated
with the same COMSOL Compiler version (having the same version of the
COMSOL Runtime).

| 39

Click Next to select the location of the COMSOL Runtime files and the click
Install, as shown in the figure below.

The installation takes a few minutes and, when finished, the installer will prompt
the user to start the application.
An option for showing the COMSOL About dialog box is always available in acompiled application. The author of the application controls how this information

40 |is available from the Settings of the Main Window; see “About Dialog” on page 135.
The figure below shows the About dialog box.

In the About dialog box, the user of a compiled application can access thePreferences by clicking the corresponding button. The Preferences dialog box for
a compiled application is shown below.

| 41

Here, the user can change settings for Visualization, Mouse, Temporary files,
Multicore, and LiveLink™ for MATLAB. These settings represent a subset of thePreferences available in COMSOL Multiphysics and more information can befound in the COMSOL Multiphysics Reference Manual.
If the compiled application detects that OpenGL graphics hardware
acceleration is not supported, then the application will automaticallyswitch to software rendering and exit. The next time the application starts,
software rendering will be used.

Publishing COMSOL Applications
The COMSOL Software License Agreement (SLA) gives you permission to
publish your COMSOL applications for others to use, including commercially,
with certain restrictions spelled out in the SLA available here:
www.comsol.com/sla. This permission enables you to share your applications withothers and to charge them for using your applications through three different
mechanisms.
First, you can make an application available to others to be run by a COMSOLMultiphysics installation. For using an application with COMSOL Multiphysics,
the user needs to belong to the same organization that purchased the COMSOLMultiphysics license.
Second, you can make an application available to others to be run by a COMSOL
Server installation. This approach allows for greater flexibility, as it allows you to
set up a COMSOL Server installation and let users from around the world accessyour Application. You just need to provide them with the address, a username, andpassword to your COMSOL Server installation. Alternatively, users can purchasetheir own COMSOL Server license. If you use COMSOL Server to host and run
applications, the SLA also gives you permission to make time on your COMSOL
Server License (CSL) available to persons outside your organization to host andrun applications that you are publishing to others, subject to certain restrictions.
Third, you can use COMSOL Compiler to compile your application into astandalone program that contains all of the functionality required to make it run.
This approach gives you the greatest flexibility, as the end user of your application
will not need a license for COMSOL Multiphysics or COMSOL Server to run the
Application. The compiled application can then be run by that user and anyone
else to whom you allow the user to publish the compiled application, around theworld, inside or outside of your organization.
The COMSOL Application License, also available at www.comsol.com/sla,further lets you modify applications available in the Application Libraries and42 |publish those modified applications for others to use, including commercially,
with certain restrictions spelled out in the Application License. This allows you to,for example, use one of the applications in the Application Libraries as a starting
point for your own applications by adding or removing your own features.
If you wish to apply the Application License to applications that you create, theApplication License contains instructions on how to do so. The Application
License also addresses how you can use terms that you choose for modifications
you make to applications available in the Application Libraries, while the original
portions of those applications remain available under the Application License.
The results from a simulation software such as COMSOL Multiphysics canshorten design times dramatically by, for example, reducing the number ofexperiments or product tests. However, simulation software is not a substitute forreal-world testing. This is especially important if there are risks for physical orenvironmental damage.

| 43

Getting Started with the Application Builder
S TARTING F ROM A COMSOL M ULTIPHYSICS M ODEL
If you do not have a model already loaded to the COMSOL Desktop
environment, select File>Open to select an MPH file from your file system or selecta file from the Application Libraries. Note that, in the Application Libraries, thefiles in the Applications folders are ready-to-use applications. All other files in the
Application Libraries contain a model and documentation, but not an application
user interface.
Once the model is loaded, click the Application Builder button in the ribbon Hometab. This will take you to the Application Builder desktop environment.

C REATING A N EW F ORM U SING T EMPLATES AND THE F ORM W IZARD
To start working on the user interface layout, click the New Form button in the
Home tab. This will launch the Form Wizard.

The Form Wizard assists you with adding the most common user interface
components, so-called form objects, to the first draft of your application.

44 |In the Form Wizard, the first page is the Select Template page.

The different templates listed here will help you quickly create an organizedapplication with different levels of sophistication and user-interface layouts fordesktop, table, and smartphone use.
For this example, select the Basic layout template and click Content. The SelectContent page has three tabs:• Inputs/outputs| 45

• Graphics• Buttons

Double-click a node or click the Add Selected button to move a node from the
Available area to the Selected area. The selected nodes will become form objects inthe application, and a preview of the form is shown in the Preview area to the right.
At the top of the wizard window, you can change the name and title of the form.
For details see “The Individual Form Settings Windows” on page 51.
The size as well as other settings for form objects can be edited after exiting the
wizard. You can also choose to exit the wizard at this stage by clicking Done, andthen manually add form objects.

The Inputs/Outputs Tab
The Inputs/outputs tab displays the model tree nodes that can serve as an input
field, data display object, check box, or combo box. Input fields added by the
wizard will be accompanied by a text label and a unit, when applicable. You canmake other parts of the model available for input and output by using Data Access(see page 104). Check box and combo box objects are, for example, only available
in this way. For example, you can make the Predefined combo box for Element Size
under the Mesh node available in the wizard by enabling it with Data Access.

46 |In the figure below, three parameters, including Length, Width, and Applied
voltage, have been selected to serve as input fields.

In the figure below, a Derived Values node has been selected to serve as a data
display object.

| 47

After exiting the wizard, you can edit the size and font color as well as othersettings for input fields and data display objects.

The Graphics Tab
The Graphics tab displays the model tree nodes that can serve as graphics objects:
Geometry, Selection, Mesh, and Results. In the figure below, two such nodes havebeen selected.

The Buttons Tab
The Buttons tab displays the model and application tree nodes that can be run byclicking a button in the application user interface. Examples of such tree nodes are
Plot Geometry, Plot Mesh, Compute Study, and each of the different plot groups
under Results. In addition, you can add buttons for GUI Commands, Forms, andMethods.

48 |In the figure below, three buttons have been added: Plot Geometry, Plot Mesh, andCompute.

Using the Form Editor, you can add buttons that run your own custom commandsequences or methods.

E XITING THE W IZARD
Click Done to exit the wizard. This automatically takes you to the Form Editor.

S AVING AN A PPLICATION
To save an application, from the File menu, select File>Save As. Browse to a folder
where you have write permissions, and save the file in the MPH file format. The
MPH file contains all of the information about the application, including
information about the embedded model created with the Model Builder.

| 49

Themes
The Settings window for Themes is displayed when you click the Themes node in
the application tree. It lets you change the overall appearance of the user interface
and forms with settings for Application theme, Image export theme, Text color,
Background color, Font, Font size, Bold, Italic, and Underline.

The default is that all new forms and new form objects inherit these settings whenapplicable.

50 |The Form Editor
Use the Form Editor for user interface layout to create forms with form objects
such as input fields, graphics, buttons, and more.

The Individual Form Settings Windows
The figure below shows the application tree node and Settings window for a form.

| 51

Each form has its own Settings window with settings for:• Name used to reference the form in other form objects and methods.
• Form Title that is used in applications with several forms.
• Icon shown in the upper-left corner of a dialog box.
• Initial size of the form when used as a dialog box or when the Main Window is

set to have its size determined by the form.
• Margins with respect to the upper-left corner (Horizontal and Vertical).
• Choices of when to store changes in dialog boxes (Store changes), see also

“Showing a Form as a Dialog Box” on page 71.
• Choices of whether the form should be Resizable or not when used as a dialog

box.
• Choices of whether to view sections as Expandable and whether they should

be Initially collapsed (Section Settings).
• Table with the formatting of all columns and rows included in the form (Grid

Layout for Contained Form Objects).
• Appearance with settings for Text color, Background color, and Backgroundimage.
• Events that are triggered when a form is loaded or closed. ( On load and On

close.)

Double-click a form node to open its window in the Form Editor. Alternatively,
you can right-click a form node and select Edit. Right-click a form window tab tosee its context menu with options for closing, floating, and tiling form windows.

S KETCH AND G RID L AYOUT M ODESThe Application Builder defaults to sketch layout mode, which lets you use fixed
object positions and size. The instructions in the section “The Form Editor”
assume that the Form Editor is in sketch layout mode unless otherwise specified.
For information on grid layout mode, see “Sketch and Grid Layout” on page 110.

52 |

I NITIAL S IZE OF A F ORM
There are two options for the initial size of a form:• Manual lets you enter the pixel size for the width and height.
• Automatic determines the size based on the form objects that the form

contains. If you are using grid layout mode and there are columns or rows
set to Grow, then the size is not defined by the form objects. In this case, thesize is estimated using the Form Editor grid size as a base point. (It will
typically be slightly larger.) You can change the grid size by dragging theright or bottom border of the grid. For more information on grid layoutmode, see “Grid Layout” on page 113.

Local Forms
Forms can be local to other forms, which enables you to create a better structure
when developing your applications. For instance, a complicated global form made| 53

up of many different subforms can have the auxiliary forms as local forms,
displayed as children in the application tree.

You can add a local form by, for example, right-clicking a global form andselecting Local Form. A global form always appears directly under the Forms nodein the application tree.

54 |F o r m E d i t o r P re f e r e n c e s
To access Preferences for the Form Editor, choose Preferences from the File menu
and select the Forms page.

The Forms section includes settings for changing the defaults for layout mode,
margins, sketch grid, and layout templates.

Form Objects

P OSITIONING F ORM O BJECTSYou can easily change the positioning of form objects such as input fields, graphics
objects, and buttons in one of the following ways:• Click an object to select it. A selected object is highlighted with a blue

frame.

| 55

• To select multiple objects, use Ctrl+click. You

can also click and drag to create a selection
box in the form window to select all objects
within it.
• Hold and drag to move to the new position.

Blue guidelines will aid in the positioning relative to other objects.
• In sketch layout mode, you can also use the keyboard arrow keys to moveobjects. Use Ctrl+arrow keys to fine tune the position.
In the figures below, a Plot button is being moved from its original position. Blue
guide lines show its alignment relative to the unit objects and the Compute button.

R ESIZING F ORM O BJECTSTo resize an object:• Click an object to select it.
• Hold and drag one of the handles, shown as blue dots, of the highlighted

blue frame. If there are no handles, this type of form object cannot be
resized.

C OPYING , P ASTING , D UPLICATING , AND D ELETING AN O BJECTTo delete an object, click to select it and then press Delete on your keyboard. You
can also click the Delete button in the Quick Access Toolbar.

56 |You can copy-paste an object by pressing Ctrl+C and Ctrl+V. Alternatively, you
can right-click an object to get menu options for Copy, Duplicate, Delete, and more.

To paste an already copied object, right-click an empty area in the form andright-click again. Depending on the copied object, a Paste menu option will beshown. In the figure below, an Input Field has previously been copied and as aresult, a Paste Input Field option is shown.

| 57

A DJUSTING P OSITION AND S IZE BY THE N UMBER OF P IXELSWhen in sketch layout mode, you can adjust the position and size of an object bytyping the number of pixels in the Position and Size section of its Settings window:• Click an object to select it. Make sure its Settings window is shown. If not,double-click the object or click the Settings button in the Form tab.
• Edit the numbers in the Position and Size section.

The Position and Size section will have different options depending on the type ofform object. For grid layout mode, there are additional settings for the position of
the object with respect to rows and columns. For details, see “Sketch and Grid
Layout” on page 110.

C HANGING THE A PPEARANCE OF D ISPLAYED T EXT
For form objects that display text, the Appearance section in the Settings windowlets you change properties such as the text displayed, font, font color, and fontsize. For some form objects, such as a button, the size of the object will adapt tothe length of the text string.

58 |In the figure below, the Settings window for a text label object is shown.

By using grid layout mode (see “Sketch and Grid Layout” on page 110) you cangain further control over the size of form objects, such as setting an arbitrary size
for a button.

S ELECTING M ULTIPLE F ORM O BJECTS
If you select more than one form object, for example, by using Ctrl+click, then the
Settings window will contain a set of properties that can be shared between theselected objects. Shared properties will always originate from the Appearance
section, the Position and Size section, or the Events section.

T HE N AME OF A F ORM O BJECT
A form object has a Name, which is a text string without spaces. The string cancontain letters, numbers, and underscore. In addition, the reserved names rootand parent are not allowed. The Name string is used in other form objects andmethods to reference the object. The path to the object is shown as a tooltip whenhovering over the Name field in the Settings window.

| 59

I NSERTING F ORM O BJECTSYou can insert form objects in addition to those created by the Form Wizard. In
the Form ribbon tab, select the Insert Object menu to see a listing of all available
objects.

The remainder of this section, The Form Editor, only describes the types of form
objects that are added by the Form Wizard. The form objects added by using the
wizard may include:• Button• Graphics• Input Field• Text Label (associated with Input Field)• Unit (associated with Input Field)• Data Display

However, when using Data Access (see page 104), the additional form objects may
be added, including:• Check Box• Combo Box

60 |For more information on the check box, combo box, and other form objects, see“Appendix A — Form Objects” on page 221.

E VENTS AND A CTIONS A SSOCIATED WITH F ORMS AND F ORM O BJECTSYou can associate objects such as buttons, menu items, ribbon buttons, forms, andform objects with actions triggered by an event. An action can be a sequence ofcommands including global methods or local methods. Local methods are notaccessible or visible outside of the forms or objects where they are defined. The
events that can be associated with an object depend on the type of object andinclude: button click, keyboard shortcut, load of a form (On load), close of a form
(On close), and change of the value of a variable (On data change).
Using Ctrl+Alt+click on a form object opens any associated method in the
Method Editor. If there is no method associated with the form object, a new local
method will be created, associated with the form object, and opened in the
Method Editor. If the form object has an associated command sequence, thissequence is converted to code and inserted in the local method.

Editor Tools in the Form Ed itor
The Editor Tools window is an important complement to the Form Wizard and theInsert Object menu for quickly creating composite form objects. To display the
Editor Tools window, click the corresponding button in the Main group in the Form
tab.

| 61

You can right-click the nodes in the editor tree to add the same set of form objects
available with the Form Wizard.

When a node is selected, the toolbar below the editor tree shows the available
options for inserting an object. You can also right-click for a list of these options.
Depending on the node, the following options are available:• Input

An Input Field, Check Box, Combo Box, or File Import object is inserted as follows:- Inserts an Input Field using the selected node as Source. It is accompanied bya Text Label and a Unit object, when applicable.
- Inserts a Check Box using the selected node as Source.
- Inserts a Combo Box using the selected node as Source. A choice list is

automatically created, corresponding to the list in the node. This option is
only available when used with Data Access (see page 104) to make thecorresponding node available in the editor tree.
- Inserts a File Import object using the selected node as File Destination.

62 |• Output- Inserts a Data Display object accompanied by a Text Label when applicable.
- Inserts a Results Table object when the selected node is a Table.
• Button- Inserts a Button object with a command sequence running the selected node.
• Graphics- Inserts a Graphics object using the selected node as Source for Initial Graphics

Content.
• Edit Node
- Brings you to the Settings window for the corresponding model tree node.

The Editor Tools window is also an important tool when working with the
Method Editor. In the Method Editor, it is used to generate code associated with
the nodes of the editor tree. For more information, see “Editor Tools in the
Method Editor” on page 176.

ButtonClicking on a Button is an event that triggers an action defined by its commandsequence. The main section of the Settings window for a button allows you to:• Edit the form object Name of the button.
• Edit the Text displayed on the button.
• Use an Icon instead of the default rendering of a button.
• Set the button Size to Large or Small.
• Set the button Style to Flat or Raised.

| 63• Add a Tooltip with text that is shown when hovering over the button.
• Add a Keyboard shortcut by clicking the input field and entering a

combination of the modifier keys Shift, Ctrl, and Alt together with anotherkeyboard key. Alt must be accompanied by at least one additional modifier.

C HOOSING C OMMANDS TO R UN
The section Choose Commands to Run lets you control the action associated with abutton-click event. The figure below shows the Settings window for a button thattriggers a sequence of four commands.

64 |A menu, ribbon, or toolbar item will also provide a Choose Commands to Run
section in its Settings window, and the functionality described in this section
applies. For more information on using menu, ribbon, and toolbar items, see“Graphics Toolbar” on page 82, “The Main Window” on page 133, “Table” onpage 291, and “Toolbar” on page 302.
To define a sequence of commands, in the Choose Commands to Run section, selecta node in the editor tree. Then click one of the highlighted buttons under the tree,
or right-click and select the command. In the figure below, the Geometry node isselected and the available commands Run and Plot are highlighted. Click Run to
add a geometry-building command to the command sequence. Click Plot to add
a command that first builds and then plots the geometry. The option Edit Nodewill take you to the corresponding node in the model tree or the application tree.

You do not need to precede a Plot Geometry command with a Build
Geometry command (that you get by clicking Run). The Plot Geometrycommand will first build and then plot the geometry. In a similar way, thePlot Mesh command will first build and then plot the mesh.
The command icons highlighted for selection are those applicable to the particulartree node. This is a list of the command icons that may be available, depending
upon the node:• Run• Plot• Set Value• Show• Show as Dialog• Import File| 65

• Enable• Disable

Some commands, such as the various plot commands, require an argument. The
argument to a plot command, for example, defines which of the different graphics
objects the plot should be rendered in.
The example below shows the Settings window and command sequence for a
Compute button as created by the Form Wizard. This button has a commandsequence with two commands: Compute Study 1 and Plot Temperature.

The Plot Temperature command has one argument, graphics1.

66 |To add or edit an input argument, click the Edit Argument button below thecommand sequence, as shown in the figure below.

To reference graphics objects in a specific form, the following syntax is used:/form1/graphics2, /form3/graphics1, etc. If a specific form is not specified, forexample, graphics1, then the form where the button is located is used.
To control the order and contents of the sequence of commands, use the Move Up,
Move Down, and Delete buttons located below the command sequence table.

| 67

C ONVERTING A C OMMAND S EQUENCE TO A M ETHOD
A sequence of commands can be automatically converted to a new method, andfurther edited in the Method Editor, by clicking Convert to Method.

Open the new method by clicking Go to Method.

68 |You can also create a method that is local to a form or form object byclicking Convert to Form Method or Convert to Local Method, respectively.
The method contains calls to built-in methods corresponding to thecommands in the commend sequence, as shown in the figure below.

In this example, the first line:
model.study(“std1”).run()runs the model tree node corresponding to the first study std1 (the first study
node is called Study 1 unless changed by the user). The second and third lines:
useGraphics(model.result("pg2"), "form1/graphics1");
useGraphics(model.result("pg1"), "form1/graphics2");

use the built-in method useGraphics to display plots corresponding to plotgroups pg1 and pg2, respectively. In this example, the plots are displayed in two
different graphics objects, graphics1 and graphics2, respectively.
For more information on methods, see “The Method Editor” on page 170.

S ETTING V ALUES OF P ARAMETERS AND V ARIABLES
The Set Value command allows you to set values of parameters and variables thatare available in the Parameters, Variables, and Declarations nodes. In addition, Set
Value can be used to set the values of properties made accessible by Data Access (see| 69page 104). The figure below shows a command sequence used to initialize a set ofparameters and a string variable.

To learn how to perform the same sequence of operations from a method, selectConvert to Method under the command table.

C HANGING WHICH F ORM IS V ISIBLE
A button on a form can also be used to display a new form. This can be done in
two ways. The first is to use the Show command, which will replace the originalform with the new form. The second is to use the Show as Dialog command. In thiscase, the new form will pop up as a dialog box over the current form, and willusually request input from the user.

70 |In the section Choose Commands to Run, you can select the Show command. The
figure below shows the command sequence for a button with a command Show
form3.

This command will leave the form associated with the button and make thespecified form visible to the user.

S HOWING A F ORM AS A D IALOG B OX
In order to use the Show as Dialog command, begin with the Choose Commands toRun section and select the form that you would like to show. The figure below| 71

shows an example of the settings for a button with the command Show form2 as
dialog.

With these settings, clicking the button in the application will launch the following
dialog box corresponding to form2:

72 |The form2 window in this example contains a text label object and an OK button,
as shown in the figure below.

In the Settings window, the Dialog Actions section has two check boxes:• Close dialog• Store changes

In the example above, the Close dialog check box is selected. This ensures that theform2 window is closed when the OK button is clicked. Since form2 does not haveany user inputs, there is no need to select the Store changes check box.
Typical dialog box buttons and their associated dialog actions are:
BUTTONDIALOG ACTIONSOKClose dialog and Store changes

CancelClose dialog

ApplyStore changes

A dialog box blocks any other user interaction with the application until it isclosed.
In order to control when data entered in a dialog box is stored, there is a list in
the Dialog Settings section of the Settings window of a form where you can select| 73

whether to store data On request or Immediately when the change occurs, as shownin the figure below.

When the Store changes option On request is selected, the variables that have beenchanged by the user in the dialog box will not be updated until the OK button (orsimilar) in the dialog box has been clicked. This requires that the check box Storechanges is selected, in the Settings window of the OK button. When the option
Immediately is selected, variables changed by the user in the dialog box is updated
immediately including while the dialog box is still open.

A PPEARANCE
In the Settings window for a button, the Appearance section contains font settings
as well as settings that control the state of the button object.

Changing the Enabled and Visible State of a Form Object
Whether or not the button object should be Visible or Enabled is controlled fromthe check boxes under the State subsection. The Appearance section for most form

74 |

objects has similar settings, but some have additional options; for example, input
field objects.
A button, or another form object, with the Visible check box cleared will not beshown in the user interface of the running application. A form object with the
Enabled check box cleared will be disabled, or “grayed out”, but still visible. The
state of a form object can also be controlled using built-in methods. For example,
assume that a Boolean variable enabled_or_disabled is used to determine theenabled/disabled state of a button with Name button3. In this case, you cancontrol the state of the button as follows:
setFormObjectEnabled("button3", enabled_or_disabled);

In a similar way, the call
setFormObjectVisible("button3", visible_or_not);lets a Boolean variable visible_or_not control whether the button is shown tothe user or not.
For more information, see “GUI-Related Methods” on page 337 and theApplication Programming Guide.

Graphics
Each Graphics object gets a default name such as graphics1, graphics2, etc.,
when it is created. These names are used to reference graphics objects in commandsequences for buttons, menu items, and in methods. To reference graphics objects
in a specific form, use the syntax: /form1/graphics2, /form3/graphics1, etc.

S ELECTING THE S OURCE FOR I NITIAL G RAPHICS C ONTENTIn the Settings window for a graphics object, use the section Source for Initial
Graphics Content to set the plot group or animation to be displayed as default. To
select, click Use as Source or double-click a node in the tree. If a solution exists forthe displayed plot group, the corresponding solution will be visualized when the| 75

application starts. The figure below shows the Settings window for a graphics
object with a Temperature plot selected as the source.

In addition to Results plot nodes, you can also use Animation, Selection, Geometry,
and Mesh nodes as the Selected source.
Selecting the check box Zoom to extents on first plot ensures that the first plot thatappears in the graphics canvas shows the entire model (zoom extents). This action
is triggered once the first time that graphics content is sent to the graphics object.
Selecting the check box Data picking makes the graphics object interactive so thatyou can, for example, click on a plot at a particular point and retrieve a numericalvalue for the temperature at that coordinate. For more information, see “DataPicking” on page 91.

A PPEARANCE
For a graphics object, the Appearance section of the Settings window has thefollowing options:• Include an Icon, such as a logo image, in the upper-right corner.

76 |• Set the background Color for 2D plots.
• Set a flat or graded background color for 3D plots by choosing a Top colorand Bottom color.

In addition, the subsection State (not shown in the figure above) contains settings
for the visible and enabled state of the graphics object. For more information, see“Changing the Enabled and Visible State of a Form Object” on page 74.

| 77

The figure below shows an application where the background Top color is set towhite and the Bottom color to gray. In addition, the standard plot toolbar is notincluded.

78 |G RAPHICS C OMMANDSIn the editor tree used in a command sequence of, for example, a button, theGraphics Commands folder contains commands to process or modify a graphics
object. The figure below shows a command sequence with one command forprinting the contents of a graphics object.

The available Graphics Commands include:• Zoom Extents- Makes the entire model visible.
• Reset Current View
- Resets the currently active view to the state it had when the application was

launched; also see “Views” on page 85.
• Scene Light- Toggles the scene light (on or off).
• Transparency- Toggles the transparency setting (on or off).
• Orthographic projection- Enable orthographic projection (as opposed to perspective projection).

| 79• Print- Prints the contents of the graphics object.
• Select All- Selects all objects.
• Clear Selection- Clear the selection of all objects.
• Show Selection Colors- Enable visualization of selection colors.
• Show Material Color and Texture- Enable visualization of material color and texture.

Note that the many of these commands have corresponding toolbar buttons in thestandard graphics toolbar. See the next section “Graphics Toolbar”.

Plot While Solving
To let the user monitor convergence, you can plot the results while solving. In thisexample, assume that the Plot option is enabled for Results While Solving. This
option is available in the Settings window of a Study node in the model tree, as
shown in the figure below.

You can include a method that calls the built-in sleep method for briefly
displaying graphics information before switching to displaying other types of80 |graphics. Insert it in a command sequence after a plot command, as shown in the
figure below.

In this example, the sleep_a_bit method contains one line of code:
sleep(1000); // sleep for 1000 ms

For more information on the method sleep, see “sleep” on page 342.
In the command sequence above, the Plot Velocity command comes before theCompute Study command. This ensures that the graphics object displays thevelocity plot while solving.

U SING M ULTIPLE G RAPHICS O BJECTSDue to potential graphics hardware limitations on the platforms where yourapplication will be running, you should strive to minimize the number of graphics
objects used. This is to ensure maximum portability of your applications. In
addition, if you intend to run an application in a web browser, there may be
additional restrictions on how many graphics objects can be used. Different
combinations of hardware, operating systems, and web browsers have different
limitations.
In this context, two graphics objects with the same name but in different forms
count as two different graphics objects. For example, form1/graphics1 andform2/graphics2 represent two different graphics objects. In addition, if agraphics object is used in a subform (see “Form” on page 261), then each use ofthat subform counts as a different graphics object.
To display many different plots in an application, you can, for example, create
buttons, toggle buttons, or radio buttons that simply plot to the same graphics
object in a form that does not use subforms.
If you need to use methods to change a plot, use the useGraphics method. For
more information on writing methods, see “The Method Editor” on page 170.

| 81

The example code below switches plot groups by reusing the same graphics object,based on the value of a Boolean variable.
if (my_boolean) {useGraphics(model.result("pg1"), "form1/graphics1");
my_boolean=!my_boolean; // logical NOT to change between true and false} else {useGraphics(model.result("pg2"), "form1/graphics1");
my_boolean=!my_boolean;}

C LEARING THE C ONTENTS OF A G RAPHICS O BJECT
You can clear the contents of a graphics object by a call to the useGraphics
method, such as:
useGraphics(null, "/form1/graphics1")

which clears the contents of the graphics object graphics1 in the form form1.

G RAPHICS T OOLBAR
The type of tree node used in the Source for Initial Graphics Content determines thetype of toolbar that is shown. The toolbar will be different depending on the spacedimension and whether the referenced source is a Geometry, Mesh, Selection, orPlot Group node. For example, the Plot Group node displays an additional Show
Legends button.
In the Settings window of a graphics object, in the Toolbar section, you can control
whether or not to include the graphics toolbar, as well as its position (Below,
Above, Left, Right). In addition, you can choose between the options Small or Large
for Icon size, Background color, and whether to Include standard toolbar items or
not.

82 |

Graphics Toolbar for Geometry and Mesh
The figure below shows the standard graphics toolbar as it appears when theGeometry or Mesh node, for a 3D model, is used as a Source for Initial Graphics
Content.

Graphics Toolbar for Selection
When the Source for Initial Graphics Content is set to an Explicit selection, thegraphics toolbar will contain three additional items: Zoom to Selection, Select Box,and Deselect Box. This is shown in the figure below.

For more information on selections, see “Selections” on page 88.

Graphics Toolbar for Plot Groups
The figure below shows the standard graphics toolbar as it appears when a 3D PlotGroup node is used as a Source for Initial Graphics Content.

Custom Graphics Toolbar Buttons
In the Toolbar section, you can also add custom buttons to the graphics toolbar.
Use the buttons under the table to add or remove custom toolbar buttons (items).
You can also move toolbar buttons up or down, add a Separator, and Edit a button.
The figure below shows a standard graphics toolbar for results with four additional
buttons to the right.

| 83

The figure below shows the corresponding settings and table of graphics toolbar
items.

84 |To edit the command sequence for a toolbar item, click the Edit button to open
the Edit Custom Toolbar Item dialog box.

This dialog box has settings that are similar to those of a button or a toolbar itemwith the contents divided into two or three tabs depending on if the item is a
toggle item or not. For details, see “Button” on page 63 and “Toolbar” on page
302.

Views
In the graphics toolbar, the Go to Default View button (for 3D graphics only) will
display a menu with all applicable views. The currently active view is indicated witha check mark.

In addition to a list of all views, there is an option Reset Current View that will resetthe currently active view to the state it had when the application was launched.

| 85

A NIMATIONS
You can display animations in an application by using a Results > Animation nodeas the Source for Initial Graphics Content.

86 |To run the animation, use the Form Wizard or the Editor Tools window to create
a command from, for example, a button that runs a Results > Animation node.

When using the Form Wizard or Editor Tools, the animation button will have thefollowing default appearance:| 87

S ELECTIONS
Selections in the Model Builder
In the Model Builder, named selections let you group domains, boundaries,
edges, or points when assigning material properties, boundary conditions, andother model settings. You can create different types of selections by adding
subnodes under the Component > Definitions node. These can be reusedthroughout a model component.
As an example of how selections can be used, consider selections for boundary
conditions. When you select which boundaries should be associated with a certain
boundary condition, you can click directly on those boundaries in the graphics
window of the COMSOL Desktop environment. This is the default option called
Manual selection (see below). These boundaries will then be added to a selectionthat is local to that boundary condition. Named selections instead let you define
global selections that can be reused for several different kinds of boundary
conditions by just selecting from a drop-down list. The figure below shows an
Explicit selection given the name Inlet Surfaces with two associated boundaries (22and 88).

88 |The figure below shows the Settings window for an Inlet boundary condition
where the Inlet Surfaces selection is used. In this example, there is also an Outlet
Surfaces selection.

For convenience, in addition to the Manual option, there is also a shortcut for All
boundaries.

Selections in the Application Builder
The Explicit selection type lets you group domains, boundaries, edges, or points
based on entity number, and is the type of selection most readily available for use
with the Application Builder. You can allow the user of an application tointeractively change which entities belong to an Explicit selection with a Selection
Input object or a Graphics object. In the example below, the embedded model has
a boundary condition defined with an Explicit selection. Both a Selection Input| 89object and a Graphics object are used to let the user select boundaries to be excitedby an incoming wave.

The user can here select boundaries by clicking directly in the graphics window,
corresponding to the Graphics object, or by adding geometric entity numbers in alist of boundary numbers corresponding to a Selection Input object.
To make it possible to directly select a boundary by clicking on it, you can link agraphics object to an Explicit selection, as shown in the figure below. Select the
Explicit selection and click Use as Source. In the figure below, there are two Explicit

90 |selections, Excitation Boundary and Exit Boundary, and the graphics object
graphics2 is linked to the selection Excitation Boundary.

When a graphics object is linked directly to a selection in this way, the graphics
object displays the geometry and the user can interact with it by clicking on theboundaries. The boundaries will then be added (or removed) to thecorresponding selection.
To make it possible to select by number, you can link a Selection Input object toan explicit selection. For more information, see “Selection Input” on page 282.
The Editor Tools window provides a quick way of adding a Graphics object or a
Selection Input object that is linked to an Explicit selection. To get these options,right-click an Explicit selection node in the editor tree.
You can let a global Event be triggered by an Explicit selection. This allows acommand sequence or method to be run when the user clicks a geometry object,domain, face, edge, or point. For more information on using global events, see“Events” on page 139 and “Source For Data Change Event” on page 141.

D ATA P ICKING
In the Settings window for a graphics object, select the check box Data picking to
make the graphics object interactive so that you can, for example, click on a plot
at a particular point and retrieve a numerical value for the temperature at thatcoordinate. In the figure below, in the section Target for Data Picking, a scalar| 91

double variable Tvalue is selected. This variable is declared under the Declarations
node. In the running application, the value of the temperature at the pointerposition will be stored in the variable Tvalue.

If the Target for Data Picking is a 1D double array, then the stored value will insteadcorrespond to the x, y (2D) or x, y, and z coordinates at the clicked position.
The Target for Data Picking can be any one of the following:• Scalar double variable• 1D double array• Domain Point Probe• Boundary Point Probe• Graphics Data declaration

For more information on Graphics Data declaration, see “Graphics Data” on page
166.

92 |

Input Field
An Input Field allows a user to change the value of a parameter or variable. In theForm Wizard, when a parameter or variable is selected, three form objects are
created:• A Text Label object for the parameter or variable description.
• An Input Field object for the value.
• A Unit object (if applicable) that carries the unit of measure.

By selecting a parameter or variable using the Editor Tools window, the same threeform objects are created.
Assuming you do not use the Editor Tools window: To insert an additional input
field, use the Insert Object menu in the ribbon and select Input Field. In the Form
Editor, you link an input field to a certain parameter or variable by selecting it fromthe tree in the Source section and click Use as Source. In the Source section of the| 93

Settings window, you can also set an Initial value. The figure below shows the
Settings window for an input field.

In addition to parameters and variables, input fields can use an Information node
as Source.
The default setting for the Initial value is From data source. This means that if thesource is a parameter, then the initial value displayed in the input field is the sameas the value of the parameter as specified in the Parameters node in the Model
Builder. The other Initial value option is Custom value, which allows an initial value
different from that of the source. If the Editable check box is cleared, then theInitial value will be displayed by the application and cannot be changed.
You can add a Tooltip with text that is shown when hovering the mouse pointerover the input field.

94 |The header of the Source section contains buttons for easy access to tools that areused to make additional properties and variables available as sources to the input
field.

The Create New Declaration and Use It as Source button can be used to add newvariables under the Declarations node. For more information, see “Declarations”
on page 146. The Create New Form Declaration and Use It as Source button can beused to add new variables under the Declarations nodes local to forms, as shown
below.

The Switch to Model Builder and Activate Data Access button can be used to accesslow-level model properties as described in the next section. For more information
on Data Access, see “Data Access in the Form Editor” on page 104.

D ATA V ALIDATIONThe Data Validation section of the Settings window for an input field allows you tovalidate user inputs with respect to units and values.

When creating an input field in the Form Wizard, the setting Append unit tonumber is used when applicable. This setting assumes that a user enters a number
into the input field, but it can also handle a number followed by a unit using the| 95

COMSOL square bracket [] unit syntax. If the Unit expression is mm, then 1[mm]is allowed, as well as any length unit, for example, 0.1[cm]. An incompatible unit
type will display the Error message. A parameter that has the expression 1.23[mm],and that is used as a source, will get the appended unit mm and the initial value
displayed in the edit field will be 1.23.
The Unit dimension check list has the following options:• None• Compatible with physical quantity• Compatible with unit expression• Append unit to number (default)• Append unit from unit set

A value or expression can be highlighted in orange to provide a warning when theuser of an application enters an incompatible unit, which is any unit of measurethat cannot be converted to the units specified in the Data Validation settings.
Enable this feature by selecting Compatible with physical quantity or Compatible
with unit expression. In addition, the user will see a tooltip explaining the unit
mismatch, as shown in the figure below.

If there is a unit mismatch, and if no further error control is performed by theapplication, the numeric value of the entered expression will be converted to thedefault unit. In the above figure, 9[kg] will be converted to 9[m].
A button Add Unit Label is available to the right of the Unit dimension check list.

Clicking this button will add a unit label to the right of the input field if there is
not already a unit label placed there.
The None option does not provide unit validation.

96 |Numerical Validation
The options Append unit to number, Append unit from unit set, and None allow you
to use a filter for numerical validation of the input numbers.

The Filter list for the option None has the following options:• None• Double• Integer• Regular expression

The Filter list for the options Append unit to number and Append unit from unit set
only allows for the Double and Integer options.
The Double and Integer options filter the input based on Minimum and Maximum
values. If the input is outside of these values, the Error message is displayed. You
may use global parameters in these fields. If global parameters are used, you candefine such parameters with or without units. If you use global parameters withouta unit, then only the numerical value of these parameters is considered when they
are used as Minimum and Maximum values. For example, consider data validationof an input field for a length parameter L with unit cm. Further, assume that a
global parameter Lmax is used as the Maximum value. If you would like themaximum value of L to be 15 cm, then the following values for the parameter Lmax
will work: 15 (with no unit), 15[cm], 0.15[m], 150[mm], etc.
For the Append unit from unit set option, the Minimum and Maximum values arealways with respect to the Initial value for the unit set by the unit set. For more
information on unit sets, see “Unit Set” on page 159.
The Regular expression option, available when the Unit dimension check is set toNone, allows you to use a regular expression for matching the input string. For
more information on regular expressions, see the dynamic help. Click the help
icon in the upper-right corner of a window and search for “regular expression”.
For more advanced requirements, note that virtually any kind of validation of thecontents of an input field can be made by calling a method using the Events sectionin the Settings window of an input field.

| 97

Error Message
You can customize the text displayed by the Error message. During thedevelopment and debugging of an application, it can sometimes be hard to deducefrom where such errors originate. Therefore, when using Test Application,
additional debugging information is displayed, as shown in the figure below.

The debugging information typically consists of the type of form object, the pathto the form object, and the reason for the failure; for example, 10<=x<=2500.
No extra information is added when launching an application by using Run
Application or COMSOL Server.

N UMBER F ORMATThe Number Format section contains a check box Use input display formatting. If
selected, it enables the same type of display formatting as a Data Display object.

For more information, see “Data Display” on page 101.

98 |

A PPEARANCE
In addition to color and font settings, the Appearance section for an input fieldcontains a Text alignment setting that allows the text to be Left, Center, or Rightaligned.

Whether the input field should be Visible or Enabled is controlled from the checkboxes under the State subsection. For more information, see “Changing the
Enabled and Visible State of a Form Object” on page 74.

| 99

Unit
In the Settings window for a Unit object, you can set the unit to a fixed string, orlink it to an source, such as an input field. The figure below shows the Settings
window for a unit object.

When adding an input field using the Form Wizard, a unit object is automatically
added when applicable. By default, the unit is displayed using Unicode rendering.
As an alternative, you can use LaTeX rendering by selecting the LaTeX markup
check box. Then, the display of units will not depend upon the selected font.

T e x t La b e l
A Text Label object simply displays text in a form. When adding an input field using
the Form Wizard, a Text Label object is automatically added for the description
text of the associated parameter or variable. There is a check box allowing for

100 |Multiline text. If selected, the Wrap text check box is enabled. The figure below
shows the Settings window for a Text Label object.

To insert an additional Text Label, use the Insert Object menu in the ribbon andselect Text Label. The contents of the section Position and Size will change
depending on if you are working in sketch layout mode or grid layout mode.

Data Display
A Data Display object is used to display the numerical values of scalars and arrays.
If there is an associated unit, it will be displayed as part of the Data Display object.

| 101

S OURCEIn the Settings window for a data display object, in the Source section, select a
node in the model tree. Then click the Use as Source button shown below. Validparameters, variables, and properties include:• The output from a Derived Values node, such as a Global Evaluation or a Volume

Maximum node
• Variables declared under the Declarations > Scalar, 1D Array, and 2D Arraynodes• Properties made available by using the Data Access tool; See “Data Access in

the Form Editor” on page 104• One of the following Information node variables, which are under the root

node and under each Study node:- Expected Computation Time

This is a value that you enter in the Expected field in the Settings window of
the root node.
- Last Computation Time (under the root node)

The is the last measured computation time for the last computed study.
- Last Computation Time (under a study node)This is the last measured computation time for that study.
When you start an application for the first time, the last measured times arereset, displaying Not available yet.

U SING THE F ORM W IZARD FOR G ENERATING D ATA D ISPLAY O BJECTSIn the Form Wizard in the Inputs/outputs tab, only the Derived Values nodes will
generate Data Display objects. Variables under Declarations and constants madeavailable with Data Access will instead generate Input Field objects.
When a Derived Values node is selected, two form objects are created based on thecorresponding Derived Values node variable:• a Text Label object for the Description of the variable• a Data Display object for the value of the variable

The settings for these form objects can subsequently be edited. To insert
additional data display objects, use the Insert Object menu in the ribbon and selectData Display.

N UMBER F ORMATThe Number Format section lets you set the Precision, Notation, Exponent, and Unit.

102 |The figure below shows an example with data display objects for the variables Coilresistance and Coil inductance. A formatted unit label is automaticallydisplayed as part of the object if applicable.

R ENDERING M ETHOD
By default, the unit of a data display object is displayed using Unicode rendering.
As an alternative, you can use LaTeX rendering by selecting the LaTeX markup
check box. Then, the data display does not rely on the selected font.
A formatted display of arrays and matrices is only supported with LaTeX
rendering. The figure below shows a 2D double array (see page 154) displayedusing a Data Display object with LaTeX markup selected.

| 103

You can add a Tooltip with text that is shown when hovering over the data display
object.

Data Access in the Fo rm Editor
The Settings window of many types of form objects has a section that allows you
to select a node in a tree structure that includes the model tree, or parts of themodel tree, and parts of the application tree. Examples include the Source sectionof an input field or the Choose Commands to Run section of a button. There aremany properties in the model and application trees that are not made available bydefault, because there may be hundreds or even thousands of properties, and thefull list would be unwieldy. However, these “hidden” properties may be madeavailable to your application by a technique called Data Access.
The remainder of this section gives an introduction to using Data Access, with
examples for input fields and buttons.

D ATA A CCESS FOR I NPUT F IELDS
By default, you can link input fields to parameters and variables defined in themodel tree under the Parameters or Variables nodes and to variables declared in
the application tree under the Declarations node. To access additional model tree
node properties, click the Switch to Model Builder and Activate Data Access buttonin the header of the Source section of the input field Settings window, as shown in
the figure below.

You can also access it from the Application group of the Developer tab of the Model
Builder.

104 |Then, when you click on a model tree node, check boxes appear next to theindividual settings. In the figure below, the check box for an Electric potential
boundary condition is selected:| 105

The figure below shows the Settings window for an input field. The list of possible
sources for this field now contains the Electric potential.

In addition, as seen in the figure above, Data Access makes it possible to access thecheck box Editable and the Tooltip text of the input field form object. In addition
to the settings of the Model Builder, Data Access lets you access certain propertiesof the Application Builder.
Data Access can be used for buttons to set the value of a parameter, variable, or amodel property. For example, you can create buttons for predefined mesh element
sizes. The settings shown in the figure below are available when, in the Settings
window of the Mesh node, the Sequence type is set to User-controlled mesh. In this106 |

example, the Predefined property for Element Size has been made available and thenselected.

| 107

The figure below shows the Settings window for a button used to create a meshwith Element Size > Predefined set to Fine.

In the above example, a Set Value command is used to set the value of thePredefined mesh size (hauto) property. The property Predefined mesh size (hauto)
corresponds to the following settings in the Size node shown earlier:

108 |PREDEFINED MESH SIZE

VALUE

Extremely fine1

Extra fine - Extra coarse

2-8

Extremely coarse

9The value of the hauto property is a double and can take any positive value. For
non-integer values, linear interpolation is used for the custom mesh parameters.
You can, for example, let a slider object adjust the predefined mesh size. For more
information on the slider object, see “Slider” on page 296.
In general, for individual model tree properties, you can quickly learn about their
allowed values by recording code while changing their values and then inspecting
the automatically generated code. For more information, see “Recording Code”
on page 180.
You can also use a combo box object to give direct access to all of the options from
Extremely fine through Extremely coarse. For more information, see “Combo Box”
on page 229.

S UMMARY OF D ATA A CCESSThe table below summarizes the availability of Data Access for form objects andevents, as well as menu, toolbar, and ribbon items.
FORM OBJECT, EVENT, OR ITEMSECTION IN SETTINGS WINDOW

Input Field

SourceButtonChoose Commands to Run

Toggle Button, Menu Toggle Item,
and Ribbon Toggle Item

Source and Choose Commands to Run

Check Box

SourceCombo Box

SourceData Display

SourceGraphics (Graphics Toolbar Item)

Choose Commands to Run

Form Collection

Active Pane Selector
Tiled or Tabbed

Card Stack

Active Card Selector

Information Card Stack

Active Information Card Selector

Radio Button

SourceText

SourceList Box

SourceSlider

SourceToolbar (Toolbar Item)

Choose Commands to Run

Menu Item

Choose Commands to Run| 109

FORM OBJECT, EVENT, OR ITEMSECTION IN SETTINGS WINDOW

Ribbon Item

Choose Commands to Run

Event (Global)

Choose Commands to Run
Source for Data Change Event

A global event, menu, ribbon, or toolbar item provides a Choose Commands to Run
section in its Settings window, to which the functionality described above in thesection on buttons also applies. Global events and many form objects provide a
Source section in its Settings window, and the functionality described above in thesection on input fields applies. For information on global events, menus, ribbons,and toolbar items, see “Graphics Toolbar” on page 82, “The Main Window” onpage 133, “Events” on page 139, “Table” on page 291, and “Toolbar” on page
302.

Sketch and Grid Layout
The Form Editor provides two layout modes for positioning form objects: sketchlayout mode and grid layout mode. The default is sketch layout mode, which lets
you use fixed positions and sizes of objects in pixels. Use grid layout mode toposition and size objects based on a background grid with cells. In grid layoutmode, a form is divided into a number of intersecting rows and columns, withat most one form object at each intersection. This layout mode is recommended
for designing a resizable user interface, such as when designing an application to
be run in a web browser on multiple platforms.

S KETCH L AYOUT
Switch between sketch and grid layout mode by clicking Sketch or Grid in the
Layout group in the ribbon.

110 |The Sketch group in the Form tab has two options: Show Grid Lines and Arrange.
The Arrange menu allows you to align groups of form objects relative to eachother.

Sketch Grid
The Show Grid Lines option displays a sketch grid to which objects are snapped.
Note that the grid used in sketch layout mode is different from the grid used ingrid layout mode. The default setting for sketch layout mode is to show no gridlines. Without grid lines visible, a form object being dragged is snapped relative tothe position of the other form objects.
If the Show Grid Lines option is selected, the upper left corner of a form object
being dragged is snapped to the grid line intersection points.

| 111

In the Settings window of the form, you can change the settings for the sketch
grid:• Column width• Row height• Align grid to margin• Snap zone
- A slider allows you to change the snap zone size from Small to Large• Snap only to grid
- Clear this check box to snap both to the grid and the position of other form

objects

Position and Size
The sketch layout mode is pixel based, and the positioning of form objects isindicated as the coordinates of the top-left corner of the form object measured
from the top-left corner of the screen. The x-coordinate increases as the object
moves to the right, and the y-coordinate increases as the object moves from the
top of the screen to the bottom. You can set the absolute position of a form object
in the Position and Size section of its Settings window.

Form objects are allotted as much space as required or as specified by their Widthand Height values. Form objects are allowed to overlap.

112 |Button and toggle button form objects have an Automatic and Manual option for
the Width and Height values. The Manual option allows for pixel-based input andthe Automatic option adapts the size of the button to the size of the Text string.

G RID L AYOUT
Switch to grid layout mode by clicking Grid in the Layout group in the ribbon.

The buttons and menus in the ribbon Grid group give you easy access tocommands for:• Changing the row and column growth rules between Fit, Grow, and Fixed,

which determine the layout when the user interface is resized (Row Settings
and Column Settings).
• Inserting or removing rows and columns ( Insert and Remove).
• Aligning form objects within grid cells (Align).
• Merging and splitting cells (Merge Cells and Split Cells).
• Extracting a rectangular array of cells as a subform and inserting it into a newform (Extract Subform).
• Defining the number of rows and columns (Rows & Columns).

| 113

The Form Settings Window and the Grid
After switching to grid layout mode, the form window shows blue grid lines.

To define the number of rows and columns, click the Rows & Columns button in
the ribbon.

114 |The section Grid Layout for Contained Form Objects in the Settings window shows
column widths and row heights.

To interactively select a form, as displayed in the Form Editor, click the top-leftcorner of the form.

A blue frame is now shown. To interactively change the overall size of a form, you
can drag its right and bottom border. The form does not need to be selected forthis to work.
Note that if you switch from sketch to grid layout mode, all rows and columns will
have the setting Fit and the handles for the frame will not be displayed. If any of
the rows and columns have the Height or Width setting set to Grow, then the frame
will display handles for resizing in the vertical or horizontal direction, respectively.

| 115

The size of the interactively resized frame will affect the initial size of the form only
if the Initial size setting is set to Automatic. The size of the frame will also affect theinitial size of the Main Window if its Initial size setting is set to Use main form’s size.

Rows and Columns
Click the leftmost cell of a row to select it. The leftmost cells are only used forselecting rows; form objects cannot be inserted there. When a row is selected, theRow Settings menu as well as the Insert and Remove commands are enabled in the
ribbon tab. The figure below shows the fourth row highlighted.

116 |Similarly, to select a column, click the cell at the top. This cell cannot contain any
form objects. The figure below shows the third column highlighted. In this case,
the Column Settings menu is enabled in the ribbon tab.

The Row Settings and the Column Settings have the same three options:• Fit sets the row height or column width to the smallest possible value given

the size of the form objects in that row or column.
• Grow sets the row height or column width to grow proportionally to theoverall size of the form.
• Fixed sets a fixed value for the number of pixels for the row height or column

width.

You can interactively change the row height and column width by dragging thegrid lines.

In this case, the number of pixels will be displayed and the Row Settings or Column
Settings growth policy will be changed automatically to Fixed.

| 117

As an alternative to changing the Row Settings or Column Settings from the ribbon,
you can right-click in a row or column and select from a menu.

The menu shown when right-clicking a row or column also gives you options for
inserting, removing, copying, pasting, and duplicating rows or columns.

Cells
Click an individual cell to select it. A selected cell is shown with deeper blue gridlines.

You can select Merge Cells and Split Cells to adjust the cell size and layout of yourform objects.

118 |When in grid layout mode, you can specify the margins that are added between
the form object and the borders of its containing cell.

In the Settings window of a form object, the Position and Size section has thefollowing options for Cell margin:• None- No cell margins• From parent form (default)- The margins specified in the Settings window of the form; See “Inherit

Columns and Cell Margins” on page 125• Custom- Custom margins applied only to this form object

If the Horizontal alignment or Vertical alignment is set to Fill and the growth policyof the column or row allows the form object to be resized, then you can specify aminimum width or height, respectively. The minimum size can be set to Manualor Automatic. The Manual option lets you specify a pixel value for the minimum
size. The Automatic option allows for a minimum size of zero pixels, unless theform object contents require a higher value. The minimum size setting is used atruntime to ensure that scroll bars are shown before the form object shrinks below
its minimum size.
Depending on the type of form object contained in a cell, the Width and Heightvalues can be set to Automatic or Manual, as described in “Position and Size” onpage 112.
You can click and drag a rubber box to select multiple cells.

| 119

Aligning Form Objects
The Align menu gives you options for aligning form objects within a cell. You canalso let a form object dynamically fill a cell horizontally or vertically.

As an alternative, you can right-click a form object and select from a context menu.

120 |Drag and Drop Form Objects
You can drag and drop form objects to move them. Click a form object to selectit, and then drag it to another cell that is not already occupied with another form
object.

If you drop the object in an already occupied cell, then the objects switch places.

Automatic Resizing of Graphics Objects
In order to make the graphics object of an application resizable, follow these steps:• Change the layout mode of the form containing the graphics object fromsketch to grid layout mode.
• Change the Height setting for any row covering the graphics object to Grow.

To change this, click the leftmost column of the row you would like to| 121

access. Then, change the Height setting in the Settings window of the form.
Alternatively, right-click and select Grow Row.

• Change the Width for any column covering the graphics object to Grow. To

change this, right-click the uppermost row of the column you would like toaccess and select Grow Column.
• Select the graphics object and change both the Horizontal alignment andVertical alignment to Fill. You can do this from the Settings window or by

122 |right-clicking the graphics object and selecting Align > Fill Horizontally andAlign > Fill Vertically.

Following the steps above, you may find it easier to make graphics objects
resizable by performing grid layout mode operations, such as adding empty rows
and columns as well as merging cells. If you are already in grid layout mode, thena graphics object will default to Fill in both directions.

Extracting Subforms
You can select a rectangular array of cells in a form and move it to a new form.
First, select the cells by using Ctrl+click or Shift+click.

Then, click the Extract Subform button in the ribbon.

| 123This operation creates a new form with the selected cells and replaces the original
cells with a form object of type Form. In the Settings window of the subform, theForm reference points to the new form containing the original cells.

124 |Inherit Columns and Cell Margins
By using subforms, you can organize your user interface, for example, by grouping
sets of input forms. The figure below shows part of a running application with two
subforms for Beam dimensions and Reinforcement bars.

For more information on adding subforms to a form, see the previous section and“Form” on page 261.
When aligning subforms vertically, as in the example above, you may want toensure that all columns are of equal width. For this purpose, you can use theInherit columns option in the Settings window of a subform. The figure below
shows part of the Settings window for the Beam dimensions subform (left) with
Name geometry_beam and for the Reinforcement bars subform (right) with Name

| 125

geometry_rebars. The geometry_rebars subform has its Inherit columns set togeometry_beam.

In the subsection Cell margins, you can specify the Horizontal and Vertical margins
that are added between form objects and the borders of their containing cells.
These settings will affect all form objects contained in the form, with theirindividual Cell margins set to From parent form; See “Cells” on page 118.

Copying Between Applications
You can copy and paste forms and form objects between multiple COMSOLMultiphysics sessions running simultaneously. You can also copy and paste within
one session from the current application to a newly loaded application.
In grid layout mode, a cell, multiple cells, entire rows, and entire columns may becopied between sessions.

126 |When you copy and paste forms and form objects between applications, the copied
objects may contain references to other forms and form objects. Such references
may or may not be meaningful in the application to which they are copied. For
more information on the set of rules applied when pasting objects, see “Appendix
B — Copying Between Applications” on page 305.
When copying and pasting between applications, a message dialog box will appear
if a potential compatibility issue is detected. In this case, you can choose to cancel
the paste operation.

Using Forms in the Model Builder
Forms without graphics form objects can be used in the Model Builder. You can
use this functionality to create customized Settings windows for, for example,
common or repetitive tasks.
To use a form, right-click Global Definitions and select the form under Settings
Forms.

| 127

You can control whether a form should be visible or not in the Model Builder asa Settings Form via the check box Show in Model Builder. This check box is available
in the Application Builder in the Settings window of the corresponding form.

Once added to the model tree, the form is shown as a Settings window, shown in
the figure below.

To show a Settings Form you can:• Click the corresponding model tree node.
• Select it from the Settings Form menu button in the Developer tab in the

ribbon.
• Show it as a dialog box by selecting it from the Show Dialog menu button in

the Developer tab in the ribbon.

For reusing a Settings Form between sessions, you can create an Add-in. For more
information, see “Creating Add-Ins” on page 211.

128 |

Inputs
When starting an application from the operating system command line, you canprovide input arguments. In the application tree, you specify such input
arguments under the Inputs node.

Command-line arguments are automatically written to the declarations you define
as Selected source, in the corresponding Settings window for an Application
Argument. They can be used, for example, to provide input data or configuration
settings.

Command-line arguments can be used when starting applications with COMSOLMultiphysics, COMSOL Server, as well as when starting applications that havebeen compiled with COMSOL Compiler. In the example below, for a compiled| 129

application in Windows, an input argument freq is given that takes a (double)
value 400.

For COMSOL Multiphysics, the corresponding command would be
comsol.exe -run myapp.mph -appargnames freq -appargvalues 400

When running this command, you need to be positioned in the COMSOLMultiphysics installation directory where the executable comsol.exe is located, forexample
C:\Program Files\COMSOL\COMSOL56\Multiphysics\bin\win64

130 |Alternatively, you can copy and paste the COMSOL Multiphysics 5.6 Windows
Desktop shortcut icon (in order to keep the original shortcut), right-click theicon, and select Properties; as shown in the figure below.

You can, for example, modify the Target text field to be:"C:\Program Files\COMSOL\COMSOL56\Multiphysics\bin\win64\comsol.exe" -runmyapp.mph -appargnames freq -appargvalues 400

To provide input arguments with special characters, you need to use single quotes.
The following example of a compiled application shows how to provide a file path,such as for a configuration file, as an input argument:
myapp.exe -appargnames configfile -appargvalues 'C:\\COMSOL\\my_conf.dat'

For COMSOL Server, you can provide the arguments directly in the address fieldof your browser (URL); for example:
http://<host:port>/app/myapp_mph?appargnames=freq&appargvalues=400

You can also use a file declaration as an input argument. This is useful, for example,
when you want to let users supply input files. For example:
comsol.exe -run file_arguments.mph -appargnames interpfile -appargvalues'C:\data\functions\simpleinterp.txt'| 131

This example uses an application argument interpfile, which is linked to a filedeclaration to read the interpolation file simpleinterp.txt when launching theapplication. This file is then used in an interpolation function in the application’s
embedded model.

132 |The Main Window
In the application tree, the Main Window node represents the main window of an
application and is also the top-level node for the user interface. It contains thewindow layout, the main menu specification, and an optional ribbon specification.

G ENERALThe Settings window contains a General section with settings for:• Title• Show filename in title• Icon• Menu type
• Status bar

The Title is the text at the top of the main window in an application, with the Icon
shown to the far left of this text. By default, the Title is the same as the title of themodel used to create the application. Keep the check box Show filename in title| 133

selected if you wish to display the file name of the application to the left of the
Title.
In the Icon list, select an image from the library or add an image (*.png) fromthe local file system to the library and use it as an icon. If you add a new image,it will be added to the image library and thereby embedded into the application.
You can also export an icon by clicking the Export button to the right of the
button Add Image to Library and Use Here.
The Main Window node of the application tree has one child node, named Menu
Bar. Using the Menu type setting, you can change this child node from Menu Bar
to Ribbon.
The Status bar list controls what is shown in the status bar. Select Progress todisplay a progress bar when applicable (the default), or None. Note that you canalso create custom progress bars by using methods.

M AIN F ORM
The Main Form section contains a reference to the form that the main window
displays. This setting is important when using a form collection because it
determines which form is displayed as the main window when the application is
opened for the first time.

S IZE
In the Size section, the Initial size setting determines the size of the main window
when the application is first started. There are three options:• Maximized results in the window being maximized when the application isrun.
• Use main form's size uses the size of the main form; See “The Individual Form

Settings Windows” on page 51. The main form is defined by the Main Form
section. This option further adds the size required by the main window
itself, including: the window frame and title bar, main menu, main toolbar,
and ribbon. This size is computed automatically and depends on whether
the menu type is Menu bar or Ribbon.
• Manual lets you enter the pixel size for the width and height. In this case,nothing is added to the width and height. When using this option, you needto ensure that there is enough room for the window title, ribbon, andmenu bar.
In addition, there is a Center on screen check box that is applicable to any Sizesetting that does not correspond to a maximized window.
For more information on the option Use main form’s size, see “The Form Settings
Window and the Grid” on page 114.

134 |

A BOUT D IALOG
The About Dialog section contains settings for customizing parts of the About This
Application dialog box, which contains legal information. The Placement option
lets you choose between Automatic, File menu, Ribbon, Lower-right corner or
Lower-left corner. The Lower-right corner and Lower-left corner options will place ahyperlink to the About This Application dialog box in the corresponding corner of
the application user interface. If selected, the Show COMSOL information check box
will display COMSOL software version and product information. Any text enteredin the Custom text field will be displayed above the legal text in the dialog box. In
the Custom text field, words containing http or www will be interpreted as
hyperlinks, if possible. For example, http://www.comsol.com or www.comsol.com
will be replaced with a hyperlink.

M e n u B a r a n d T o o l b ar
The Menu Bar node can have Menu child nodes that represent menus at the top
level of the Main Window.

| 135

For the Menu Bar option, you can also add a Toolbar. The Toolbar node and theMenu nodes have the same type of child nodes.

M ENU , I TEM , AND S EPARATOR
The child nodes of the Menu and Toolbar nodes can be of type Menu, Item, Toggle
Item, or Separator, exemplified in the figure below:

136 |A Menu node has settings for Name and Title.

A Menu node can have child Menu nodes that represent submenus.
A Separator displays a horizontal line between groups of menus and items, and has
no settings.
The Settings window for an Item node is similar to that of a button and contains asequence of commands. Just like a button, an item can have associated text, an
icon, and a keyboard shortcut. For more information, see “Button” on page 63.
In a similar way, the Settings window for a Toggle Item node is similar to that of a
toggle button.
The figure below shows the Settings window for an Item associated with a method
for save an application.

| 137

The figure below shows an example of an application with a File menu.

You can enable and disable ribbon, menu, and main toolbar items from methods.
For more information, see “Appendix E — Built-In Method Library” on page331.

R ibbonYou can opt to add a Ribbon to the Main Window instead of a Menu Bar. The Ribbon
node contains the specifications of a ribbon with toolbars placed on one or several
tabs. For the Ribbon option, a File menu is made available directly under the Main
Window node.

R IBBON T AB AND R IBBON S ECTION
Child nodes to the Ribbon node are of the type Ribbon Tab. Child nodes to a Ribbon
Tab are of the type Ribbon Section. Child nodes to a Ribbon Section can be of thetype Item, Toggle Item, Menu, or Separator.
Item and Menu provide the same functionality as described previously for the Menu
Bar and Toolbar. A Separator added as a child to a Ribbon Section is a vertical linethat separates groups of Items and Menus in the running application. A Separator

is displayed as a horizontal line in the application tree. The figure below shows anexample.

138 |Events
An event is any activity (for example, clicking a button, typing a keyboard
shortcut, loading a form, or changing the value of a variable) that signals a needfor the application to carry out one or more actions. Each action can be a sequenceof commands of the type described earlier, or may also include the execution of
methods. The methods themselves may be local methods associated withparticular forms or form objects, or global methods that can be initiated fromanywhere in the application. The global methods are listed in the Methods node of
the application tree. The form methods are listed under the nodes of the respective
form. The local methods are defined in the Settings windows of the forms or form
objects with which they are associated. When a form object has an associatedmethod, it may be opened for editing by performing a Ctrl+Alt+click on theobject. If the Ctrl+Alt+click is performed on a form object that has no method,then a new local method, associated with the object, will be created and opened
for editing.
The events that initiate these actions may also be global or local. The global eventsare listed in the Events node of the application tree and include all events that are
triggered by changes to the various data entities, such as global parameters or
string variables. Global events can also be associated with the startup andshutdown of the application. The local events, like local objects, are defined in the
Settings windows of the forms or form objects with which they are associated.
Event nodes trigger whenever the source data changes, regardless of if it is changed
from a method, form object, or in any other way. Events associated with form
objects only trigger when the user changes the value in the form object.

| 139

Events at Startup and Shutdown
Global or local methods can be associated with the events at startup (On startup)and shutdown (About to shutdown) of an application. To access these events, click
the Events node in the application tree.

A shutdown event is triggered when:• The user of an application closes the application window by clicking the Close

Application icon in the upper-right corner of the application window• The Exit Application command is issued by a form object• A method is run using the command exit()

A method run at a shutdown event can, for example, automatically save critical
data or prompt the user to save data. In addition, a method run at a shutdown
event may cancel the shutdown by returning a Boolean true value.

L IMITATIONS WITH O N S TARTUP E VENTS
Methods used for an On startup event cannot utilize Application Builder
functionality related to graphics or user interfaces. This is due to the fact that an
On startup event is run before the full application user interface is loaded. For
example, a method that is used for initializing graphics, such as Zoom Extents,
needs to be run as an On load event for a form and not as a global On startup event.
Another example is showing a dialog box using a built-in method such as confirm.
In this case, no dialog box will be shown and the operation will simply be ignored.

Global Events
Right-click the Events node and choose Event to add an event to an application.
An event listens for a change in a running application. If a change occurs, it runs

140 |

a sequence of commands. In the figure below, when the value of the string variable
SpanWidth is changed, the method setResultsStatus is run.

Note that since this type of event has global scope and is not associated with aparticular form, the full path: /form1/graphics1 needs to be used whenreferencing graphics objects.
The following two sections describe the options available in the Settings windowof an event.

S OURCE F OR D ATA C HANGE E VENTThis section presents a filtered view of the tree from the Application Builder
window. The nodes represent some sort of data or have children that do.

| 141

You can extend the list of available data nodes by clicking on the Switch to Model
Builder and Activate Data Access button in the header of the section Source For Data
Change Event.

For more information, see “Data Access in the Method Editor” on page 178.
Note that Explicit selections are also allowed as Source for Data Change Event. This
allows a command sequence or a method to be run when the user clicks ageometry object, domain, face, edge, or point. The figure below shows a dialog

142 |box for a global event that opens a form panel as a dialog box when the userchanges the contents of the Explicit selection named Outlet.

C HOOSE C OMMANDS TO R UN
In the Settings window for an Event, the section Choose Commands to Run is similar
to that of a button and allows you to define a sequence of commands. For more
information, see “Button” on page 63.

| 143

F o r m a n d F o r m O b j e ct E v e n t s
Form and form object events are similar to global events, but are defined for forms
or individual form objects. These events have no associated list of commands, butrefer directly to one global, form, or local method.

E VENTS T RIGGERED BY D ATA C HANGE
For certain types of form objects, you can specify a method to run when data ischanged. This setting is available in the Events section of the Settings window of aform object, as shown in the figure below.

The drop-down list On data change contains None (the default), any available
methods under the Methods node of the application tree or under the Methods
node of the corresponding form, and a local method (optional).
The form objects supporting this type of event are:
• Input Field• Check Box• Combo Box• Graphics• File Import• Array Input• Radio Button• Text• List Box• Table• SliderButtons have associated events triggered by a click. Menu, ribbon, and toolbar
items have associated events triggered by selecting them. The corresponding
action is a command sequence defined in the Settings window of a button object
or item. For more information on command sequences, see “Button” on page 63.

Selecting Multiple Form Objects
You can specify an On data change event for multiple form objects simultaneously
by using Ctrl+click and then selecting the method to run. In this way, you can, forexample, quickly specify that a data change event initiated by any of the selected

144 |form objects should run a method that informs the user that plots and outputs areinvalid. This functionality is not available for all combinations of form objects.

E VENTS T RIGGERED BY L OADING OR C LOSING A F ORM
Forms can run methods when they are loaded (On load) or closed (On close).

This type of event is available in the Settings window of a form and is typically used
when a form is shown as a dialog box, or to activate forms used as panes in a form
collection. Note that a method that is used for initializing graphics, such as Zoom
Extents, needs to be run as an On load event for a form and not as a global On
startup event.

Using Local Methods
Events can call local methods that are not displayed in the application tree. For
more information on local methods, see “Local Methods” on page 193.

| 145

Declarations
The Declarations node in the application tree is used to declare global variables andobjects, which are used in addition to the global parameters and variables alreadydefined in the model. Variables defined under the Declarations node are used inform objects and methods. In form objects, they store values to be used by otherform objects or methods. Variables that are not passed between form objects andmethods, but that are internal to methods, do not need to be declared in the
Declarations node. In methods, variables defined under the Declarations node haveglobal scope and can be used directly with their name. For information on how toaccess global parameters defined in the model tree, see “Accessing a Global
Parameter” on page 202.
You can create a Declarations node that is local to a form. Such Declarations for aform can only be used in that particular form, including form objects and methods
that are local to the form.
These are the different types of global Declarations:• Scalar• Array 1D• Array 2D• Choice List
• File• Unit Set• Shortcuts• Graphics Data

Form Declarations can only be of the types:• Scalar• Array 1D• Array 2D• Choice List

146 |

Right-click a Declarations node to access the declaration types or use the ribbon.

Note that Shortcuts are not created from this menu but by clicking the Create
Shortcut button next to the Name in the Settings window of a form object or byusing Ctrl+K for a selected form object.
To create Declarations that are local to a form, right-click the corresponding formand select the variable type, as shown below.

Variables that are local to a form are organized under a Declarations node that is achild node to the form, as shown below.

The first three types of declarations, Scalar, Array 1D, and Array 2D, can be of thefollowing data types:• String• Boolean| 147

• Integer• Double

In addition to right-clicking the Declarations node, you can click the Create New
Declaration and Use It as Source button in the Source section of many types of form
objects.

This will open a dialog box that lets you quickly declare scalar variables.

U SING D ECLARATIONS AS I NPUT A RGUMENTS TO C OMMANDS
Certain commands used in the commands sequence of, for example, a button cantake an input argument. For more information, see “Button” on page 63.

148 |The figure below shows a command sequence that includes a Plot Temperaturecommand with an input argument form1/graphics.

You can use declarations as input arguments to commands.
To use a scalar variable, 1D array, or 2D array as input arguments, you use thecorresponding variable name. To access a single element of an array, or a row orcolumn of a 2D array, use indexes. For example, to access the first component in
a 1D array my_variable, you use my_variable(1). A 2D array element can be
retrieved as a scalar by using two indexes, for example, my_matrix(2,3). The
indexes can themselves be other declared variables, for example, my_variable(n).
For commands requiring a graphics object as an input argument, only string typedeclarations are allowed with appropriate indexes, if necessary. If there is agraphics object named graphics1 and also a string declaration named graphics1,
then the contents of the string declaration will be used. An exception is if single
quotes are used, such as 'graphics1', in which case the graphics object
graphics1 is used. This rule is also applied to other combinations of commands
and input arguments.

T HE N AME OF A V ARIABLE
The Name of a variable is a text string without spaces. The string can containletters, numbers, and underscores. The reserved names root and parent are notallowed and Java programming language keywords cannot be used.

| 149

Scalar
Scalar declarations are used to define variables to be used as strings, Booleans,
integers, or doubles.

S TRINGA scalar string variable is similar to a global parameter or variable in a model, butthere is a difference. A parameter or variable in a model has the restriction that its
value has to be a valid model expression, while a scalar string variable has no such
restrictions. You can use a string variable to represent a double, integer, or
Boolean by using conversion functions in a method. For more information, see“Conversion Methods” on page 344. You can also use a string variable as a source
in many form objects, such as input fields, combo boxes, card stacks, and list
boxes.
The figure below shows the Settings window for the string variablesgraphics_pane, email_to, and solution_state.

String declarations, as well as other declarations, can be loaded and saved from or
to a file by using the Load from File and Save to File buttons below the List of
Variables table.
The Load from File and Save to File buttons are used to load and save from/to thefollowing file formats:• Text File (.txt)

150 |• Microsoft Excel Workbook (.xlsx)- Requires LiveLink™ for Excel®
• CSV File (.csv)• Data File (.dat)

The drop-down list where these file formats can be selected is shown in the figure
below.

To illustrate the use of declared strings, the figure below shows the Settings
window of a card stack object where the string variable viewCard is used as thesource (Active Card Selector).

For more information on using card stacks, see “Card Stack” on page 265.

| 151

B OOLEAN
You can use a Boolean variable as a source in check boxes, other form objects, andmethods. A Boolean variable can have two states: true or false. The default value
is false. The figure below shows the declaration of two Boolean variables.

Example CodeIn the example code below, the Boolean variable bvar has its value controlled bya check box. If bvar is true, then Plot Group 4 (pg4) is plotted in graphics1.
Otherwise, Plot Group 1 (pg1) is plotted.
if (bvar) {useGraphics(model.result("pg4"),"graphics1");} else {useGraphics(model.result("pg1"),"graphics1");}

I NTEGER AND D OUBLE
Integer and double variables are similar to strings, with the additional requirementthat the value is an integer or double, respectively.

152 |Array 1D
The Array 1D node declares one or more named arrays of strings, Booleans,
integers, or doubles that you can access from form objects and methods. The
number of elements in a 1D array is not restricted in any way, and you can, forexample, use a 1D array to store a column in a table with a variable number ofrows. The Settings window contains a single table, where you specify one variable
array per row. In the figure below, two double arrays are declared, xcoords andycoords.

The values in the column New element value are assigned to new elements of thearray when a row is added to a table form object. Arrays for strings, Booleans, andintegers are similar in function to arrays of doubles.

I NITIAL V ALUESThe Initial values can be a 1D array of arbitrary length. To edit the initial values,
click the Edit Initial Values button below the List of Variables. This opens a dialog
box where the value of each component can be entered. See the figure below foran example of a 1D array of doubles.

| 153

A RRAY S YNTAXAn array definition must start and end with curly braces ({ and }) and eachelement must be separated with a comma. When you need special characters inside
an array element (spaces and commas, for example), surround the element withsingle quotes ('). The table below shows a few examples of 1D arrays:
ARRAY SYNTAXRESULTING ARRAY{1, 2, 3}A 3-element array with the elements 1, 2,
and 3

{}

An empty array{'one, two', 'three by four'}A 2-element array with elements containing
special characters{{1, 2, 3},{'one, two', 'three by
four'}}

A 2-element array containing a 3-element
array and a 2-element arrayA r r ay 2 D
The Array 2D node declares one or more 2D arrays that you can access using form
objects and methods. In the figure below, the 2D double array xycoords is
declared.

I NITIAL V ALUES
The default (or initial) value can be a 2D array of arbitrary size. To edit the initialvalues, click the Edit Initial Values button below the List of Variables. This opens a

154 |dialog box where the value of each component can be entered. See the figure
below for an example of a 2D array of doubles.

A RRAY S YNTAXThe table below shows a few examples of 2D arrays:
ARRAY SYNTAXRESULTING ARRAY{{}}

An empty 3D array{{'5','6'},{'7','8'}}

A 2-by-2 matrix of strings{{1, 2, 3}, {4, 5, 6}}

A 2-by-3 matrix of doubles

For 2D arrays, rows correspond to the first index so that {{1,2,3},{4,5,6}} isequivalent to the matrix:
1 2 3
4 5 6

Assuming that the above 2-by-3 matrix is stored in the 2D array variable arr, thenthe element arr[1][0] equals 4.
To interactively define the Initial values of a 2D array, select the Undefined option
for the Number of columns. The Edit Initial Values button opens a dialog box where| 155the number of rows and columns can be interactively changed, as shown in the
figure below.

Choice List
The Choice List node contains lists that can be used by combo boxes, radio
buttons, or list boxes. The Settings window for a choice list contains a Label, aName, and a table with a Value column and a Display name column. Enter theproperty value (Value) in the first column and the corresponding text to display tothe user (for example, in a combo box list) in the second column (Display name).

156 |The Value is always interpreted as a string. In the example below, mat1 will become
the string "mat1" when returned from the combo box.

As an alternative to creating a choice list by right-clicking the Declarations node,
you can click the Add New Choice List button in the Settings window for form
objects that use such a list, as shown in the figure below.

In addition you can click the adjacent Add New Form Choice List to create a choicelist local to the form.

A CTIVATION C ONDITION
You can right-click the Choice List node to add an Activation Condition subnode.
Use an activation condition to switch between two or more choice lists contingent
on the value of a variable. For an example of using choice lists with activation
conditions, see “Using a Combo Box to Change Material” on page 237.

| 157

File
File declarations are primarily used for file import in method code when using thebuilt-in method importFile. For more information on the method importFile
and other methods for file handling, see “File Methods” on page 332. However,an entry under the File declaration node can also be used by a File Import object.
The figure below shows the Settings window of a file declaration.

The file chosen by the user can be referenced in a form object or method using
the syntax upload:///file1, upload:///file2, etc. The file name handle(file1, file2, etc.) can then be used to reference an actual file name picked by
the user at run time.
For more information on file declarations and file handling, see “Appendix C —File Handling and File Scheme Syntax” on page 307.

158 |

Unit Set
The Unit Set node contains lists that can be used by combo boxes, radio buttons,
or list boxes for the purpose of changing units. The Settings window for a unit set
contains two sections: Unit Groups and Unit Lists.

Each row in the Unit Groups table is a unit group that represents a collection ofunits with a particular meaning in the context of the application user interface.
Each column represents a group of units labeled by a Value and a Display name.
Each row in the Unit Lists table is a unit list with columns containing units withthe same dimension, for example, mm, cm, dm, m, and km. The headings of theUnit Lists table are Name and the Display names are defined in the Unit Groups
section. A unit list specifies the possible units that a form object that references theUnit Set can switch between when running the application.
The figure above demonstrates the use of a Unit Set for an application that allows
for switching between metric and imperial units. In this example, two unit groups
are defined: SI and Imperial. The Label of the Unit Set has been changed to Unit
System.
The Value column contains string values that represent the current choice of unitgroup. These string values can be manipulated from methods. The Display name| 159

column is the string displayed in the user interface. The Initial value list contains
the default unit group (SI in the example above).
In the example above, the Unit Lists table has three columns: Name, SI, andImperial. The SI and Imperial columns are created dynamically based on the groups
in the Unit Groups section. Each row in the table corresponds to a physical quantity
such as, in this example, length and potential. Each column in the tablecorresponds to the allowed units of length and units of potential, respectively.
The figure below shows an example application where a combo box form object
is used to choose between the SI and Imperial unit groups.

160 |The figure below shows the Settings window of a combo box using the Unit Set ofthe above example as the Source.

In this way, a Unit Set can be used instead of a Choice List to create a combo box
for unit selection. Instead of a combo box, you can use a list box or a radio button
object in a similar way.

| 161

The two figures below show the corresponding Settings windows for the two input
fields for Length and Applied voltage.

The Unit dimension check is set to Append unit from unit set. The Unit set is set to
Unit System {unitset1} (the user-defined label for the Unit Set declaration used inthis example). The Unit list is set to length and potential, respectively. When using
Append unit from unit set, the Numerical validation section (under Data Validation)refers to the Initial value of a Unit Set; in this case, cm and mV, respectively. The
Minimum and Maximum values are scaled automatically when the application is run
and the unit is changed by the user of the application. For more information on
the settings for an input field object, see “Input Field” on page 93.

162 |The figures below illustrate the use of two Unit Set declarations for separately
setting the unit for length and potential, respectively.

The figures below show the corresponding Settings window for the Unit Set
declarations.

Note that, in this example, by using three Unit Set declarations, you can haveindividual length unit settings for the Length and Width input fields. The figure| 163

below shows such an example, where three combo boxes have been used toreplace the unit labels and each combo box uses a separate Unit Set declaration as
its source.

When more flexibility is required, you can combine the use of a Choice List and a
Unit Set. For example, for a combo box, you can use the Unit Set as the Selectedsource (string) and select a Choice List that is not a Unit Set.

Shortcuts
Form objects and other user interface components are referenced in methods byusing a certain syntax. For example, using the default naming scheme
form3/button5 refers to a button with the name button5 in form3 andform2/graphics3 refers to a graphics object with the name graphics3 in form2.
You can also change the default names of forms and form objects. For example, if
form1 is your main form, then you can change its name to main.
To simplify referencing form objects as well as menu, ribbon, and toolbar items by
name, you can create shortcuts with a custom name. In the Settings window of an
object or item, click the button to the right of the Name field and type a name ofyour choice.

To create or edit a shortcut, you can also use the keyboard shortcut Ctrl+K.

164 |All shortcuts that you create are made available in a Shortcuts node underDeclarations in the application tree.

In the Settings window for Shortcuts below, two shortcuts, plot_temp and
temp_vis, have been created for a button and a graphics object, respectively.

The shortcuts can be referenced in other form objects or in code in the Method
Editor. The example below shows a shortcut, temp_vis, used as an input
argument to a temperature plot.

Shortcuts are automatically updated when objects are renamed, moved, copied,and duplicated. They are available in methods as read-only Java variables, just likestring, int, double, and Boolean declarations.
Using shortcuts is recommended because it avoids the need to adjust Method
Editor code when the structure of the application user interface changes.

| 165

Shortcuts are also available in the Model Builder, for use with the Application
Builder. In the Settings window of a model tree node, click the button to the rightof the Label field and type a name of your choice.

The custom name of a shortcut becomes available as a global variable in methods
and will be used, for example, when recording code or new methods.

Graphics Data
A Graphics Data declaration node is used to pick data at a specific coordinate froma graphics object based on mouse clicks by the user. The figure below shows thecorresponding Settings window.

The Initial Values section contains default values for the extracted data properties
Coordinate and Results evaluation. The section Initial Values for 3D Geometry Source
contains settings for the selection methods available when the Source for Initial
Graphics Content of a graphics object is set to a geometry node.

166 |The different properties of a graphics data declaration are available from the Editor
Tools window as shown in the figure below.

| 167

To use a Graphics Data declaration node for data picking, select the Data picking
check box in the Settings window of a graphics object and select the Graphics Data
node as the Target for Data Picking, as shown in the figure below.

G RAPHICS D ATA FROM R ESULTS
When the Source for Initial Graphics Content of a graphics object is set to a plotgroup node, then the Results Evaluation value corresponds to the field value at theposition determined by the mouse pointer. The Coordinate value corresponds tothe coordinate at that position. Note that in the Model Builder, this corresponds
to the data displayed in the Evaluation 2D or Evaluation 3D tables.

168 |The figure below shows a data display object where the Coordinate property is used
as Source.

You can also use the Coordinate property as the Source for an array input object.
The Results Evaluation property can be used as the Source for several form objects
including data display and input field objects.

G RAPHICS D ATA FROM G EOMETRY
The settings Geometry Entity Level, Line Entry Method, Depth Along Line, and Point
Being Modified only apply when the Source for Initial Graphics Content of a graphics
object is set to a 3D geometry node. These settings provide the same point
selection methods as a Domain Point Probe, when Geometry Entity Level is set toDomain; and Boundary Point Probe, when Geometry Entity Level is set to Boundary.
The settings Line Entry Method, Depth Along Line, and Point Being Modified are only
applicable when Geometry Entity Level is set to Domain.

| 169

The Method Editor
Use the Method Editor to write code for actions not included among the standard
run commands of the model tree nodes in the Model Builder. The methods may,for example, execute loops, process inputs and outputs, and send messages andalerts to the user of the application.
The Java programming language is used to write COMSOL methods, whichmeans that all Java syntax and Java libraries can be used. In addition to theJava libraries, the Application Builder has its own built-in library for building
applications and modifying the model object. The model object is the data
structure that stores the state of the underlying COMSOL Multiphysics modelthat is embedded in the application. More information about these built-in
methods can be found in “Appendix E — Built-In Method Library” on page 331
and in the Application Programming Guide.
The contents of the application tree in the Application Builder are accessed
through the application object, which is an important part of the model object.
You can record and write code using the Method Editor that directly accesses andchanges user interface aspects of the running application, such as button texts,
icons, colors, and fonts.
There are global methods, form methods, and local methods. Global methods are
displayed in the application tree and are accessible from all methods and form
objects. Form methods are displayed in the application tree as child nodes to theform it belongs to. A local method is associated with a form object or event andcan be opened from the corresponding Settings window. For more information
about local methods, see “Local Methods” on page 193.
A number of tools and resources are available to help you create code formethods. These are covered in the following sections and will make you
more productive by allowing you to copy-paste or autogenerate blocks ofcode, for example.

Converting a Command Sequence to a Method
In the Form Editor, select Convert to Method from the menu button displayed in
the Settings window below an existing command sequence. The commandsequence is automatically replaced by an equivalent method. In the same way you
can select Convert to Form Method and Convert to Local Method.

170 |Consider a case where you have created a compute button and you want to bealerted by a sound when the computation has finished. Now, we will see how this
could be done using the Method Editor.
You will also learn how to do this without using the Method Editor later in thissection. The figure below shows the Settings window of the Compute button.

| 171

Click the Convert to Method button below the command sequence.

The command sequence in this example is replaced by a method, method3.
Click the Go to Method button. The Method Editor opens with the tab formethod3 active.

In the Method Editor, add a call to the built-in method playSound to play thesound file success.wav, available in the COMSOL sound library, by using thesyntax shown in the figure below.

The newly added line is indicated by the green bar shown to the left.

172 |Note that in the example above, you do not have to use the Method Editor. In
the command sequence, select the file success.wav under Libraries > Sounds andclick the Run command button under the tree, as shown in the figure below.

However, there are many built-in methods that do not have corresponding
command sequence nodes. For more information, see “Appendix E — Built-In
Method Library” on page 331.

| 173

F ORM O BJECT WITH A SSOCIATED M ETHOD
A form object that has an associated method is indicated with a special icon in theForm Editor, as shown in the figure below. In this example, both the check box
called Find prong length and the Compute button have associated methods.

Performing Ctrl+Alt+Click on the form object opens the method in the Method
Editor. If there is no method associated with the form object, a new local method
associated with the form object will be created and opened in the Method Editor.
If the associated method has a compile error, then this is shown with a different
icon, as shown in the figure below.

174 |Language Elements Window
The Language Elements window in the Method Editor shows a list of somelanguage constructs. Double-click or right-click one of the items in the list to
insert template code into the selected method.

See also “Language Element Examples” on page 199.

| 175

Editor Tools in the Method Editor
To display the Editor Tools window, click the corresponding button in the Maingroup in the Method tab.

When using the Editor Tools window in the Method Editor, you can right-click anode in the editor tree to generate code associated with that node. Depending on
the node, up to eight different options are available:
• Get
• Set
• Set All
• Create• Run• Enable• Disable• Edit NodeSelecting one of the first seven options will add the corresponding code to thecurrently selected method. The Edit Node option brings you to the Settings
window for the model tree node.

176 |The figure below shows an example of a node with six options.

When a node is selected, the toolbar below the editor tree shows the available
options for generating code.
The Editor Tools window is also an important tool when working with the Form
Editor. For more information, see “Editor Tools in the Form Editor” on page 61.

| 177

K EYBOARD S HORTCUTS
Consider a method with a line of code that refers to a model object in thefollowing way:model.result("pg3").feature("surf1").create("hght1", "Height");

If you position the mouse pointer in "surf1" and press F11 on the keyboard,right-click and select Go to Node, or click Go to Node in the ribbon, then thecorresponding Surface plot note is highlighted in the Editor Tools window.
Click Edit Node to open its Settings window. For more information on keyboard
shortcuts, see “Appendix D — Keyboard Shortcuts” on page 328.

D a ta A c c e s s i n t h e M e t h o d E d i t o r
To access individual properties of a model tree node, click the Data Access buttonin the Application section of the Developer tab in the Model Builder ribbon.

Alternatively, for certain form objects, you can click the Data Access button in theheader of the Source section of the Settings window. See also “Data Access in theForm Editor” on page 104.
Data Access needs to be enabled this way because a model typically contains

hundreds or even thousands of properties that could be accessed, and the list
would be too long to be practical.
When you click a model tree node, such as the Heat Flux node in the figure below,
check boxes appear next to the individual properties. This example is based on thebusbar tutorial model described in Introduction to COMSOL Multiphysics.

178 |In the figure below, the check boxes for Heat transfer coefficient and External
temperature are selected:

If you switch to the Editor Tools window, you will see additional nodes appear
under the Heat Flux node. Right-click and use Get or Set to generate code in an
active method window, as shown in the figure below.

In the example above, Get and Set for the Heat transfer coefficient and the External
temperature properties will generate the following code:| 179model.physics("ht").feature("hf1").getString("h");model.physics("ht").feature("hf1").getString("Text");
model.physics("ht").feature("hf1").set("h", "htc");model.physics("ht").feature("hf1").set("Text", "293.15[K]");

Recording Code
Click the Record Code button in the Code section of the Method Editor ribbon torecord a sequence of operations that you perform using the model tree, as shownin the figure below.

Certain operations in the application tree can also be recorded, including methods
used to modify the user interface while the application is running such as changing
the color of a text label.
To record a new method, click the Record Method button in the Main section of
the Form Editor or Method Editor ribbon.

You can also click the Record Method button in the Developer tab of the Model
Builder ribbon.

180 |While recording code, the COMSOL Desktop windows are surrounded by a redframe:| 181

To stop recording code, click one of the Stop Recording buttons in the ribbon ofeither the Model Builder or the Application Builder.

The previous section on Data Access explained how to set the values of the Heattransfer coefficient and the External temperature properties of the busbar tutorialmodel. To generate similar code using Record Code, follow these steps:• Create a simple application based on the busbar model (MPH file).
• In the Model Builder window, click Record Method, or with the Method

Editor open, click Record Code.
• Change the value of the Heat transfer coefficient to 5.
• Change the value of the External temperature to 300[K].
• Click Stop Recording.
• If it is not already open, open the method with the recorded code.

The resulting code is listed below:
with(model.physics("ht").feature("hf1"));set("h", "5");set("Text", "300[K]");
endwith();

In this case, the automatic recording contains a with() statement in order to makethe code more compact. For more information on the use of with(), see “TheWith Statement” on page 201.
To generate code corresponding to changes to the application object, use Record
Code or Record Method, then go to the Form Editor and, for example, change theappearance of a form object. The following code corresponds to changing thecolor of a text label from the default Inherit to Blue:
with(app.form("form1").formObject("textlabel1"));set("foreground", "blue");endwith();For more information on modifying the model object and the application object,
see the Application Programming Guide.
Use the tools for recording code to quickly learn how to interact with the model
object or the application object. The autogenerated code shows you the names ofproperties, parameters, and variables. Use strings and string-number conversions
to assign new parameter values in model properties. By using Data Access while
recording, you can, for example, extract a parameter value using get, process its

182 |value in a method, and set it back into the model object using set. For more
information on Data Access, see “Data Access in the Method Editor” on page 178.

Checking Syntax
Click Check Syntax in the ribbon to see messages in the Errors and Warnings
window related to syntax errors or unused variables.

In addition to messages in the Errors and Warnings window, syntax errors areindicated with a wavy red underline, as shown in the figure below.

| 183

Find and Replace
Click Find in the Quick Access Toolbar to open a dialog box used to find andreplace strings in methods, as shown in the figure below.

The Quick Access Toolbar is located above the ribbon to the left, in the
COMSOL Desktop user interface.
The All tab is used to find strings and variables in both the Model Builder and theApplication Builder.

184 |Model Expressions Window
The Model Expressions window in the Method Editor shows a list of predefined
expressions used as input and output arguments. Double-click or right-click oneof the items in the list to insert an expression:

Use Shortcut
If you look at the example below, you will notice that the two last lines of code
begins with model.result(”pg1”).

| 185

The Use Shortcut button simplifies code by replacing these instances with a variable
name.
In the example above, the mouse pointer has been positioned at the firstoccurrence of model.result(”pg1”). Click the Use Shortcut button to transformthe source code into what is shown in the figure below.

The code starting with the prefix model.result(”pg1”) has been replaced withthe variable pointplot. When you click the Use Shortcut button, a Use Shortcut
dialog box opens where you can enter a suitable variable name in the Name field,in this case pointplot.

This variable is stored as a shortcut in the Declarations node, as shown in the figure
below together with the corresponding Settings window.

186 |S y n ta x H i g h l i g h t i n g , C o d e F o l d i n g , a n d I n d e n t a t i o n
Different language elements in the code are displayed using different styles. Referto the figure below for an example:

This example includes five styles:• Keywords, such as if, else, for, while, double, and int are displayed inbold blue font
• Built-in methods are displayed in italic blue font
• Strings are displayed in red font
• Comments are displayed in green font
• The remainder of the code is displayed in black font

You can customize the syntax highlighting theme in the Preferences dialog box.
See the next section Method Editor Preferences.
You can expand and collapse parts of the code corresponding to code blocks thatare part of for, while, if, and else statements. This feature can be disabled, as
described in the next section “Method Editor Preferences”.
When writing code, use the Tab key on your keyboard to automatically indent aline of code and insert white spaces where needed. As an alternative, you can| 187right-click in the Method Editor and select Indent and Format, as shown in the
figure below.

Indentation and whitespace formatting also happen automatically when the
keyboard focus leaves the Method Editor. You can disable this behavior in
Preferences in the Method section by clearing the check box Indent and format
automatically.
Using the context menu shown above, when right-clicking, you can togglecomments on and off for an entire block of code that you have selected. This isavailable by selecting Toggle Comment from the menu or the keyboard shortcut
Ctrl+7.

T HE N AME OF A M ETHODThe Name of a method is a text string without spaces. The string can containletters, numbers, and underscores. The reserved names root and parent are notallowed and Java programming language keywords cannot be used.

188 |Method Editor Preferences
To access the Preferences for the methods, choose File > Preferences and select the
Methods section.

By default, the Method Editor only shows the most relevant code. To see all codein a method, select the View all code check box.
The check box Close brackets automatically controls whether the Method Editor
should automatically add closing brackets, such as curly brackets {}, brackets [],and parentheses ().
The check box Generate compact code using ‘with’ statements controls theutilization of with statements in automatically generated code. For more
information, see “The With Statement” on page 201.
If the check box Enable code folding is selected, you can expand and collapse partsof the code corresponding to code blocks associated with for, while, if, and elsestatements.
Selecting the check box Indent and format automatically will ensure that code isconsistently indented and formated.
The Use component syntax option will generate method syntax that also includes
the model component scope.

| 189

Under Syntax highlighting, the Theme list contains two predefined themes, Modern(the default) and Classic. Choose User defined to define a syntax highlighting mode
where the colors can be assigned to individual language elements.
Clear the option Ask for confirmation before running methods in the Model Builder
if you do not want to confirm when running methods in this way.

C t r l + S p ac e a n d T a b f o r C o d e C o m p l e t i o n
While typing code in the Method Editor, the Application Builder can provide
suggestions for code completions. The list of possible completions are shown in a
separate completion list that opens while typing. In some situations, detailed
information appears in a separate window when an entry is selected in the list.
Code completion can always be requested with the keyboard shortcut Ctrl+Space.
When accessing parts of the model object, you will get a list of possible
completions, as shown in the figure below:

Select a completion by using the arrow keys to choose an entry in the list and press
the Tab or Enter key to confirm the selection.
If the list is long, you can filter by typing the first few characters of the completion
you are looking for.
For example, if you enter he first few characters of a variable or method name andpress Ctrl+Space, the possible completions are shown:

190 |In the example above, only variables that match the string iv are shown. This
example shows that variables local to the method also appear in the completionsuggestions.
You can also use Ctrl+Space to learn about the syntax for the built-in methods thatare not directly related to the model object. Type the name of the command anduse Ctrl+Space to open a window with information on the various calling
signatures available.

For a list of available built-in methods, you can use the Language Elements window
described on page 175 or see “Appendix E — Built-In Method Library” on page
331.
Similar information is displayed in a tooltip when hovering over the different partsof a method call, property name, declaration, or shortcut.

| 191

The keyboard shortcut Ctrl+Space can also be used in the Model Builder. For
example, when typing in an Expression field in Results, use Ctrl+Space to seematching variables, as shown in the figure below.

Creating Local Variables
You can automatically set the type of a local variable. For example, you can typex = model.geom()and click the Create Local Variable button in the Code group of the Method tab in
the ribbon.

The code is then changed to
GeomList x = model.geom()

where GeomList is the data type of model.geom().

192 |Local Methods
You can add local methods to buttons, menu items, and events. Local methods do
not have nodes displayed under the Methods node in the application tree. In themethod window for a local method, its tab displays the path to its associated userinterface component, as shown in the figure below for the case of a check box
object.

In the Form Editor, you can right-click a form object and select Create Local
Method from a menu, as shown in the figure below.

| 193

L OCAL M ETHODS FOR B UTTONS , M ENU I TEMS , AND G LOBAL E VENTSFor buttons, ribbons, menus, toolbar items, and global events, you can add a local
method by selecting Convert to Local Method from the toolbar menu button under
the sequence of commands, as shown in the figure below.

The function of this button is similar to the Convert to Method and Convert to Form
Method buttons, described in the section “Creating a New Method” on page 18.
The only difference is that it creates a local method not visible in the global
method list in the application tree. It also opens the new method in the Method
Editor after creating it. Ctrl+Alt+Click can be used as a shortcut for creating the
local method. Clicking the button Go to Method will open the local method. The
figure below shows a call to a local method associated with a button.

194 |To avoid any risk of corrupting code in a local method, you are unable to use
Convert to Method when there is a local method present in the command sequence.

L OCAL M ETHODS FOR F ORM AND F ORM O BJECT E VENTSTo add a local method for a form or form object event, click the Create Local
Method button in the Events section of the Settings window. The selected On datachange method changes from None to Local method, as shown in the figure below,
and the Method Editor is opened.

To open an existing local method in the Method Editor, click the Go to Source
button. Click the Remove Local Method button to delete the local method.
As an alternative to Ctrl+Alt+Click, you can right-click a form object and select
Edit Local Method or Edit Method from its context menu.

For more information, see “Events” on page 139.

Methods with Input and Output Arguments
A method is allowed to have several input arguments and one output argument.
You define input and output arguments in the Settings window of an active
method window. If the Settings window is not visible, click Settings in the Methodtab of the ribbon. The figure below shows a method with two input arguments,
var and coords; and one output, coordsout. The method adds random values to| 195

the array, coords. The degree of randomness is controlled by the input variable
var. The new values are stored in the array coordsout.

When you call another method from a method, Ctrl+Alt+double-click opens thewindow for that method. A method is allowed to call itself for the purpose ofrecursion.

196 |Debu gging
For debugging purposes, click in the gray column to the left of the code line
numbers to set breakpoints, as shown in the figure below.

In the ribbon, the Debug group contains the tools available for debugging
methods. When you run the application, the method will stop at the breakpoints.
Click the Step button to go to the next line in the method. The figure above showsa method currently stopped at the line highlighted in yellow.
Click Continue to run the method up until the next breakpoint. Click Stop to stoprunning the method. Click Step Into to step into the next method, if possible. Use
Remove All to remove all break points. Instead of removing, you can disable all| 197

break points by clicking Disable All. Click the Debug Log to display debugging
messages in a separate Debug Log window, as shown in the figure below.

Use the debugLog command to display the value of variables in the Debug Log
window. The code below illustrates using the debugLog command to display thevalues of strings and components of a 1D double array.
int len=xcoords.length;if (selected==0) {for (int i = 0; i < len; i++) {double divid=double(i)/len;xcoords[i] = Math.cos(2.0*Math.PI*divid);ycoords[i] = Math.sin(2.0*Math.PI*divid);debugLog("x:");debugLog(xcoords[i]);debugLog("y:");debugLog(ycoords[i]);debugLog("selected is 0");
}
}

198 |

For more information on built-in methods for debugging, see “Debug Methods”
on page 340 and the Application Programming Guide.

St o pping a M e t ho d
You can stop the execution of a method while testing an application by using the
keyboard shortcut Ctrl+Pause. A dialog box appears, as shown below.

The Model Object
The model object provides a large number of methods, including methods forsetting up and running sequences of operations. The Convert to Method, Record
Code, Editor Tools, and Language Elements utilities of the Method Editor produce
statements using such model object methods. For more information and example
code related to the model object and its methods, see “Appendix C—Language
Elements and Reserved Names” in the book Introduction to COMSOLMultiphysics, the Application Programming Guide, as well as the Programming
Reference Manual.

Language Element Examples
The Javaprogramming language is used to write COMSOL methods, whichmeans that Java statements and syntax in general can be used. This section
contains simple examples of some of the most common language elements. For
more information and examples, see the Application Programming Guide and
the Programming Reference Manual.

| 199

U NARY AND B INARY O PERATORS IN THE M ODEL O BJECT
The table below describes the unary and binary operators that can be used whenaccessing a model object, such as when defining material properties and boundary
conditions, and in results, expressions used for postprocessing and visualization.
PRECEDENCE LEVELSYMBOLDESCRIPTION

1() {} .

grouping, lists, scope

2

^

power

3

! - +

unary: logical not, minus, plus

4

[]

unit

5

* /

binary: multiplication, division6+ -binary: addition, subtraction

7< <= > >=comparisons: less-than, less-than or equal,
greater-than, greater-than or equal

8

== !=

comparisons: equal, not equal

9&&logical and

10||

logical or11,element separator in lists

U NARY AND B INARY O PERATORS IN M ETHODS (J AVA  S YNTAX )The table below describes the most important unary and binary operators used inJava code in methods.
PRECEDENCE LEVELSYMBOLDESCRIPTION

1

++ --

unary: postfix addition and subtraction

2++ -- + - !

unary: addition, subtraction, positive sign,
negative sign, logical not

3

* / %

binary: multiplication, division, modulus

4+ -binary: addition, subtraction

5!

Logical NOT

6< <= > >=comparisons: less than, less than or equal,
greater than, greater than or equal

7

== !=

comparisons: equal, not equal

8&&binary: logical AND

9||binary: logical OR

10?:

conditional ternary

200 |PRECEDENCE LEVELSYMBOLDESCRIPTION

11= += -= *= /=%= >>= <<= &=^= |=assignments

12,element separator in lists

A CCESSING A V ARIABLE IN THE D ECLARATIONS N ODE
Variables defined in the Declarations node are available as global variables in amethod and need no further declarations.

B UILT - IN E LEMENTARY M ATH F UNCTIONS
Elementary math functions used in methods rely on the Java math library. Some
examples:Math.sin(double)
Math.cos(double)
Math.random()Math.PI

T HE IF S TATEMENT
if(a<b) {alert(toString(a));} else {alert(toString(b));}

T HE F OR S TATEMENT// Iterate i from 1 to N:
int N=10;
for (int i = 1; i <= N; i++) {// Do something}

T HE W HILE S TATEMENT
double t=0,h=0.1,tend=10;
while(t<tend) {//do something with t
t=t+h;}

T HE W ITH S TATEMENT// Set the global parameter L to a fixed value
with(model.param());
set("L", "10[cm]");| 201

endwith();The code above is equivalent to:model.param().set("L", "10[cm]");A CCESSING A G LOBAL P ARAMETER
You would typically use the Editor Tools window for generating code for setting
the value of a global parameter. While in the Method Editor, right-click theparameter and select Set.
To set the value of the global parameter L to 10 cm:
model.param().set("L", "10[cm]");To get the global parameter L and store it in a double variable Length:
double Length=model.param().evaluate("L");The evaluation is in this case with respect to the base Unit System defined in themodel tree root node.
To return the unit of the parameter L, if any, use:
String Lunit=model.param().evaluateUnit("L");To write the value of a double to a global parameter, you need to convert it to astring. The reason is that global parameters are model expressions and may contain
units.
Multiply the value of the variable Length with 2 and write the result to theparameter L including the unit of cm.
Length=2*Length;model.param().set("L", toString(Length)+"[cm]");To return the value of a parameter in a different unit than the base Unit System,
use:
double Length_real = model.param().evaluate("L","cm");

If the parameter is complex valued, the real and imaginary part can be returned asa double vector of length 2:
double[] realImag = model.param().evaluateComplex("Ex","V/m");C OMPARING S TRINGS
Comparing string values in Java has to be done with .equals() and not with the== operator. This is due to the fact that the == operator compares whether thestrings are the same objects and does not consider their values. The below codedemonstrates string comparisons:boolean streq=false;
String a="string A";
String b="string B";

202 |streq=a.equals(b);// In this case streq==false
streq=(a==b);// In this case streq==falseb="string A";
streq=a.equals(b);// In this case streq==true

A LERTS AND M ESSAGESThe methods alert, confirm, and request display a dialog box with a text string
and optional user input. The following example uses confirm to ask the user if a
direct or an iterative solver should be used in an application. Based on the answer,
the alert function is then used to show the estimated memory requirement forthe selected solver type in a message dialog box:
String answer = confirm("Which solver do you want to use?","Solver Selection","Direct", "Iterative");if(answer.equals("Direct")) {alert("Using the direct solver will require about 4GB of memory whensolving.");} else {alert("Using the iterative solver will require about 2GB of memory whensolving.");}

Running Methods in the Model Builder
Running methods in the Model Builder is similar to calling methods fromapplications with the most important difference being that from the Model
Builder methods can directly modify the model object in the current session.
Running methods from the Model Builder can be used to automate modelingtasks that consist of several manual steps. For example, in a model with multiple
studies, you can record code for the process of first computing Study 1; thencomputing Study 2, which may be based on the solution from Study 1; and so on.
From the Model Builder you can call methods directly through Method Calls or theDeveloper tab in the ribbon, described later in this section. You can call methods
indirectly through Settings Forms, for example, by calling a method at the click of
a button. For more information on Settings Forms, see “Using Forms in the Model
Builder” on page 127.
In contrast to methods that are called from applications, methods called from theModel Builder cannot use built-in graphics methods such as printGraphics,
useGraphics, and zoomExtents. This restriction is due to the fact that a Settings| 203Form cannot include a graphics object (this restriction will be lifted in futureversions).
Methods called in the Model Builder may have input and output arguments. Input
arguments to such methods that are called directly, and not indirectly from a
Settings Form, are given by adding a Method Call node under Global Definitions, see“Method Calls” on page 208.

C ONTROLLING W HICH M ODEL T REE N ODE S HOULD B E A CTIVE
To control which model tree node should be active after running a method in the
Model Builder you can use the built-in method selectNode. For example, amethod modifying the geometry can have as its last line of code:
selectNode(model.component("comp1").geom("geom1"));

which will display the geometry and select the Geometry node.
The method selectNode has no function when used in an application.

G ENERATING A R EPORT A UTOMATICALLY AFTER C OMPUTINGAs an example of using a method from the Model Builder, consider the process offirst computing the solution and then generating a report. This can be automatedby first recoding the corresponding operations in the Model Builder and thenrunning a method.

204 |Let’s start from the busbar example described in the book Introduction to
COMSOL Multiphysics. You can load this example MPH file from the Application
Libraries, as shown in the figure below.

• Open the model.
• In the model tree, right-click the Report node under Results.
• Select Brief Report.
• Change the Output format to Microsoft Word (this example would also

work with the default HTML format).
• Click the Browse button and select a file name in a location on your systemthat you have write permissions to, for example:
C:\COMSOL\BusbarReport.docx• Click Write to generate and save the report to file.

| 205

• Close the Microsoft Word document that was automatically opened.
• Click the Developer tab in the ribbon (of the Model Builder) and click the

Record Method button.

• In the model tree, right-click the Study 1 node and select Compute (or use theribbon option for Compute).
• In the model tree, right-click the Report 1 node and select Write (if prompted

to overwrite, answer Yes).
• Click the Developer tab in the ribbon and click on the Stop Recording button.

• Close the Microsoft Word document.
• You can now switch over to the Application Builder, by clicking on the

Application Builder button in the ribbon, and see the recorded method in theapplication tree and in the Method Editor.

For more information on code generated from the Study node, see theApplication Programming Guide.

206 |• Here you can inspect and edit the generated code and also change the nameof the method to, for example, compute_and_report.

• Go back to the Model Builder by clicking on the Model Builder button in the

ribbon.
• In Global Definitions > Parameters, change the Length to 15[cm].

• In the ribbon, click on the Developer tab and select compute_and_report fromthe Run Method menu (if prompted to confirm, answer Yes).

Depending on your security settings, you may get an error message. To avoid thiserror, open File>Preferences, go to the Security page, and change File system accessto All files. You can change this back to its default setting after running thisexample.
Note that you can create multiple methods and call them from the Model Builder.

| 207

M ETHOD C ALLSA call, in the Model Builder, to a method for a specific set of input argument
values can be made by adding a Method Call node under Global Definitions. To add
a Method Call node, right-click Global Definitions and select one of the methods thatyou have created. The figure below shows a Method Call to a method for creating
a geometric array.

The user interface layout of a Method Call cannot be customized. Instead, forcustomizing use a Settings Form, see “Using Forms in the Model Builder” on page127.
You can run, stop, or edit a Method Call by clicking the corresponding toolbar
button in the Settings window, as shown in the figure below.

208 |This functionality is also available from the Developer tab in the ribbon of theModel Builder, as shown in the figure below.

The figure below show the corresponding method’s Settings window in the
Application Builder with the definitions of the input arguments.

You can add multiple Method Call nodes for the same method where each call cancontain a different set of input argument values.
There is no direct way of using output arguments from a method in the Model
Builder. However, you can use calls to the built-in method message to display
variables used in a method in the Messages window in the COMSOL Desktop
environment. The following example shows how to display the value of two
double variables width and depth in the Messages window:
message("Width: "+toString(width));message("Depth: "+toString(depth));For debugging purposes you can instead use the debugLog method described in
the section “Debugging” on page 197.

| 209

For reusing a Settings Form between sessions, you can create an Add-in. For more
information, see “Creating Add-Ins” on page 211.

210 |

Creating Add-Ins
To customize the workflow in the Model Builder, you can use a Method Call or a
Settings Form. However, these are associated with a specific MPH file, and you
may want to reuse them between sessions or share them with colleagues. To makethis possible, you can create an add-in based on a Method Call or Settings Form.
Such add-ins can then be stored in a user-defined add-in library. In addition,
COMSOL Multiphysics comes with built-in add-in libraries. For the add-ins in thebuilt-in library, you can review their Application Builder settings, including forms
and methods, to quickly learn how to build your own add-ins. Creating an add-in
is similar to creating an application, with a few differences. Add-ins do not havetheir own graphics window, but instead use the main Graphics window in the
Model Builder. An add-in should work, or give controlled error messages, for any
type of model.
To create an add-in, start from a form that you have created in the Application
Builder and click Add-in Definitions in the ribbon, as shown below.

Right-click the Add-in Definitions node in the application tree and select FormDefinition.

The figure below shows the Settings window for the Form Definition. Here, you cantype a Label for the add-in form as well as select which form to use for the add-in.
The Label will be displayed in the user-defined add-in library. You can selectwhether the form should be displayed as a Settings form in the model tree or as a

| 211

Dialog box. The Allow multiple settings forms check box is used to allow for morethan one instance of the Settings form in the model tree. The Description isdisplayed in the add-in library and as a tooltip when choosing among add-ins in
the ribbon.

212 |Click the Add-in Definition node to see its Settings window, as shown below.

The Filename is the location of the add-in MPH file in the user-defined add-in
library. This location can be on a shared network drive if you wish to share the
add-in with your colleagues. The Label will be displayed in the Add-in Libraries
window. The Unique identifier is what identifies the add-in and is intended to be
unique for any COMSOL Multiphysics session. The unique identifier isrecommended to be in a format similar to <company name>.<Add-in name> ;forexample, my_company.my_add-in. The Editing password will be applied to thecreated add-in and is different from the editing password that you can specify inthe root node Settings window of the MPH file used to create the add-in.

| 213

To create the add-in, which is a special type of MPH file, click the Create Add-in
button.

Add-In Libraries
To use an add-in from the Add-in Libraries, you first need to enable it. In theDeveloper tab in the Model Builder, click Add-in Libraries.

In the list of add-ins, select the check boxes of those add-ins that you want toenable.

214 |Once enabled, the corresponding add-ins will be displayed when clicking the
Add-ins button in the Developer tab.

The figure below shows the Settings Form for one of the built-in add-ins.

If you want to review and edit the Application Builder settings for a built-in
add-in, you can open the corresponding MPH file. In a typical Windows
installation, the built-in add-in library is located at:
C:\Program Files\COMSOL\COMSOL56\Multiphysics\addins

You can browse to a user-defined add-in library by clicking the Add User Add-in
Library button at the bottom of the Add-in Libraries window.

| 215

The user-defined add-in library will be displayed alongside the built-in add-in
libraries, as shown below.

Workflow when Creating and Editing Add-Ins
When creating and editing add-ins, you will find it useful to have two sessions of
COMSOL Multiphysics open at the same time: one session for the original add-in
MPH file where you work mostly in the Application Builder, and one session for
testing the add-in in the Model Builder. When testing an add-in using the Model
Builder, make sure to test for a great variety of models, including models ofdifferent spatial dimensions as well as models with more than one modelcomponent. Use the Refresh Add-ins button to make sure you always use an
updated version of the add-in you are editing.

216 |Libraries
In the application tree, the Libraries node contains images, sounds, and files to beembedded in an MPH file so that you do not have to distribute them along withthe application. In addition, the Libraries node may contain Java utility classnodes and nodes for external Java and C libraries. For more information on
using utility classes and external libraries, see the Application Builder
Reference Manual.

Embedded files can, for example, be referenced in form objects or in methods byusing the syntax embedded:///file1, embedded:///file2, and so on. For
example, to reference the image file compute.png, use the syntax
embedded:///compute.png.
Note that you are not required to have the file extension as part of the file name;instead, arbitrary names can be used. To minimize the size of your MPH file,delete unused images, sounds, or other files.
To manage files loaded by the user of an application at run time, you haveseveral options, including using File declarations and File Import form
objects. For more information on files to be loaded at run time, see “File”
on page 158, “File Import” on page 270, and “Appendix C — File
Handling and File Scheme Syntax” on page 307.

| 217

Images
The Images library contains a number of preloaded sample images in the PNG fileformat. If you wish to embed other image files, click the Add File to Library button
below the List of Images. A large selection of images is available in the COMSOL
installation folder in the location data/images. Images are used as icons and canbe referenced in image form objects or in methods. For images used as icons, twosizes are available: 16-by-16 pixels (small) and 32-by-32 pixels (large).

Supported image formats are JPG, GIF, BMP, and PNG.
To preview an image, click the name of the image in the List of Images. The image
is displayed in the Preview section
To export a selected image, click the Export Selected Image File button to the rightof the Preview button.

SoundsThe Sounds library contains a few preloaded sounds in the WAV-file format. If you
wish to embed other sound files, click the Add File to Library button below the List

218 |of Sounds. A larger selection of sounds is available in the COMSOL installation
folder in the location data/sounds.

To play a sound, click the name of the sound and then click the Preview button
below the List of Sounds.
Click the Export Selected Sound File button to the right of the Preview button toexport a selected sound.
To play a sound in an application, add a command in the Settings window of abutton, ribbon, menu, or toolbar item. In the Choose Commands to Run section,
select the sound and click the Run button below the tree. This adds a Playcommand to the command sequence, as shown in the figure below.

In methods, you can play sounds using the built-in method, playSound, such as:
playSound("success.wav");| 219

FilesThe Files library is empty by default. Click the Add File to Library button to embed
files of any type in your application.

Click the Export Selected File button to the right of the Add File to Library button
to export a selected file.

The embedded files can be referenced in a method by using the syntax
embedded:///data1.txt, embedded:///data2.txt, and so on. For more

information, see “File” on page 158, “Appendix C — File Handling and File
Scheme Syntax” on page 307, and “File Methods” on page 332.

220 |

Appendix A — Form Objects
This appendix provides information about forms and form objects and expands
upon the section “The Form Editor” on page 51. The items followed by a * in thefollowing list have already been described in detail in that section. The remaining
items are discussed in this appendix.

List of All Form Objects• Input- Input Field*- Button*- Toggle Button- Check Box- Combo Box• Labels- Text Label*- Unit*- Equation- Line• Display- Data Display*- Graphics*- Web Page
- Image- Video- Progress Bar- Log- Message Log- Results Table| 221

• Subforms- Form- Form Collection- Card Stack• Composite- File Import- Information Card Stack- Array Input- Radio Button- Selection Input• Miscellaneous- Text- List Box- Table- Slider- Knob- Hyperlink- Toolbar- Spacer

Toggle Button
A Toggle Button object is a button with two states: selected and deselected, as
shown in the figure below.

The information in this section is also applicable to Menu Toggle Item and Ribbon
Toggle Item.

U SING A T OGGLE B UTTON TO E NABLE AND D ISABLE A H EAT S OURCE
The two states of a toggle button are stored by linking it to a Boolean variable.
The figure below shows the Settings window of a button that enables and disables

222 |a heat source depending on its state. The Boolean variable heat_source is selectedin the Source section.

Enabled corresponds to the Boolean variable heat_source being equal to true,
which in turn corresponds to the toggle button being selected. Disabledcorresponds to the Boolean variable heat_source being equal to false, which inturn corresponds to the toggle button being deselected. The Icon is displayedwhen the toggle button is not selected. When the toggle button is selected, theSelected icon is displayed.

| 223

Below the Source section is the Choose Commands to Run section, with a choice for
Action that represents two different commands for Select and Deselect. The figure
below shows the Settings window for Deselect with a command Disable Heat Source.

224 |The next figure shows the command sequence for Select with a command Enable
Heat Source.

A toggle button is similar to a check box in that it is linked to a Boolean variable.
For a toggle button, you define the action by using a command sequence, whereas
for a check box, you define the action by using an event. This is described in thenext section.

Che c k Bo x
A Check Box has two values: on for selected and off for cleared. The state of acheck box is stored in a Boolean variable in the Declarations node.

| 225

U SING A C HECK B OX TO C ONTROL V ISUALIZATION
The figure below is from an application where a deformation plot is disabled or
enabled, depending on whether the check box is selected.

The screenshot on the left shows the running application. The screenshot on theright shows the corresponding form objects in grid layout mode.
In the example below, the state of the check box is stored in a Boolean variable
deformation, whose Settings window is shown in the figure below.

226 |The figure below shows the Settings window for the check box.

You associate a check box with a declared Boolean variable by selecting it from thetree in the Source section and clicking Use as Source.
The text label for a check box gets its name, by default, from the Description fieldof the Boolean variable with which it is associated.
The Initial value of the variable deformation is overwritten by the Value forselected (on) or the Value for cleared (off) and does not need to be edited. Whenused in methods, the values on and off are aliases for true and false, respectively.
These values can be used as Booleans in if statements, for example.
The code statements below come from a local method that is run for an On datachange event when the value of the Boolean variable deformation changes.
model.result("pg1").feature("surf1").feature("def").active(deformation);useGraphics(model.result("pg1"), "graphics1");| 227

U SING A C HECK B OX TO E NABLE AND D ISABLE F ORM O BJECTSThe figure below shows a part of an application where certain input fields are
disabled or enabled, depending on if the check box is selected.

The figure below shows the Settings window for a check box associated with a
Boolean variable findlength used to store the state of the check box.

The code statements below come from a local method that is run for an On datachange event when the value of the Boolean variable findlength changes.
setFormObjectEditable("main/inputfield1", !findlength);
setFormObjectEditable("main/inputfield5", findlength);
setFormObjectEnabled("main/inputfield5", findlength);
setFormObjectEditable("main/inputfield6", findlength);
setFormObjectEnabled("main/inputfield6", findlength);solution_state = "inputchanged";228 |C ombo B o x
A Combo Box can serve as either a combination of a drop-down list box and an
editable text field or as a drop-down list box without the capability of editing.

U SING A C OMBO B OX TO C HANGE P ARAMETERS IN R ESULTS
To illustrate the use of a combo box, consider an application where the user selects
one of six different mode shapes to be visualized in a structural vibration analysis.
This example uses a Solid Mechanics physics interface with an Eigenfrequency
study and is applicable to any such analysis.
These six mode shapes correspond to six different eigenfrequencies that the user
selects from a combo box:

In this example, the combo box is used to control the value of a string variable
mode. The figure below shows the Settings window for this variable.

| 229

Selecting the Source
The figure below shows the Settings window for this combo box.

In the Source section, you select a scalar variable that should have its value
controlled by the combo box and click Use as Source. In the Initial values list of theSettings window of the combo box, choose a method to define a default value forthe combo box. The options are First allowed value (the default) and Custom
default. For the Custom default option, enter a default value in the associated field.
The default value that you enter must exist among the allowed values.

Choice List
The vibrational modes 1–6 correspond to trivial rigid body modes and are not ofinterest in this application, hence the first mode of interest is 7. A choice list allows
you to hide the actual mode values in the model from the user by only displaying
the strings in the Display name column; the first nonrigid body modes are named
Fundamental tone, Overtone 1, Overtone 2, etc.

230 |In the section for Choice List, you can add choice lists that contribute allowed
values to the combo box. The Choice List declaration associated with this example
is shown in the figure below.

The string variable mode is allowed to have one of these six values: 7, 8, 9, 10, 11,
or 12. The text strings in the Display name column are shown in the combo box.
In the Settings window of the combo box, you can select the Allow other values
check box to get a combo box where you can type arbitrary values. Such combo
boxes can accept any value and are not restricted to the values defined by the
choice lists. In this example, however, only six predefined values are allowed.
For more information on choice lists, see “Choice List” on page 156.

EventsIn the Events section, specify a method to run when the value of the combo box,
and thereby the string variable used as the source, is changed by the user. In thepresent case, the value of the variable mode is changed, and a local method is run,as shown below.

The code for the local method is listed below.
with(model.result("pg1"));set("looplevel", new String[]{mode});endwith();model.result("pg1").run();| 231

This code links the value of the string mode to the Eigenfrequency setting in the
Plot Group pg1. In this case, the string svar takes the values "7", "8", "9", "10","11", or "12".
The code above can be generated automatically by using the recording facilities ofthe Method Editor:• Go to the Model Builder and, in the Developer tab, click Record Method.
• By default, when using an Eigenfrequency study for a structural mechanicalanalysis, a Mode Shape plot group is created. In this plot group, change the
Eigenfrequency from mode 7 to mode 8. In the figure below, this corresponds
to changing from 440 Hz to 632.89 Hz in the Settings window for the Mode
Shape plot group.

• Click Stop Recording.

The resulting code is shown below.
with(model.result("pg1"));set("looplevel", new String[]{"8"});endwith();model.result("pg1").run();Now change the string "8" with the variable mode to end up with the code listing
above. This will be stored in a method, say, method1. To create the local method

232 |associated with the combo box, copy the code from method1. Then, delete
method1.

Using Data AccessA quicker, but less general way, of using a combo box is to use Data Access in
combination with Editor Tools. For the example used in this section, you start byenabling Data Access and, in the Settings window of the Mode Shape plot group,
select the Eigenfrequency, as shown in the figure below.

In the Editor Tools window, the Eigenfrequency parameter is visible as Loop Level.
To create a combo box, right-click Loop Level and select Input.

The generic name Loop Level is used for a solution parameter. If a solution has two
or more parameters, then there are two or more loop levels to choose from.

| 233

The figure below shows the Settings window of the corresponding combo box.

The choice list Loop Level is automatically generated when inserting a combo box
using Editor Tools. Note that a choice list generated in this way is not displayed
under the Declarations node and cannot be modified by the user. For greater
flexibility, such as giving names to each parameter or eigenfrequency value, youneed to declare the choice list manually, as described in the previous section.

U SING A C OMBO B OX TO C HANGE T IMESThe time parameter list specified in a Time Dependent study step can be used inmany places under the Results node. In an application, the individual timeparameters can be accessed in a similar way to what was described in the lastsection for parameters, by using Data Access in combination with Editor Tools.

234 |In the Settings window in the figure below, Data Access has been used to access theTime parameter list in a temperature plot.

In Editor Tools, a handle to the Time list is now available, as shown in the figure
below.

| 235

By selecting Input, you can create a combo box using it as Source, as shown in the
figure below.

The combo box can be used for multiple purposes, for example, to update a plotcorresponding to a different time parameter. In order for a plot to automatically
update when a user uses the combo box to select a new time parameter, add anevent to the combo box at the bottom of its Settings window. In the figure below,
a method plot_T is called for updating a temperature plot.

The line of code below shows the contents of the method plot_T:
model.result("pg1").run();236 |The end result is a combo box in the application user interface, shown in the figure
below, which automatically updates a temperature plot when the user selects a newvalue for the Time list.

U SING A C OMBO B OX TO C HANGE M ATERIAL
Consider an application where combo boxes are used to select the material. In thiscase, an activation condition (see “Activation Condition” on page 157) can also
be used for greater flexibility in the user interface design.
The figure below shows screenshots from an application where the user can choose
between two materials, Aluminum or Steel, using a combo box named Material. A
second combo box called Alloy shows a list of Aluminum alloys or Steel alloys,
according to the choice made in the Material list.

| 237

The material choice is implemented in the embedded model using global materials
and a material link, as shown below.

Each material is indexed with a string: mat1, mat2, ..., mat5. An event listens forchanges to the value of the global variable alloy, where the value is controlled by
a combo box. When the value is changed, the method listed below is run.
with(model.material("matlnk1"));set("link", alloy);endwith();238 |The figure below shows the declaration of two string variables, material andalloy, which are controlled by the Material and Alloy combo boxes, respectively.

The application utilizes three choice lists: Aluminum Alloys, Steel Alloys, andMaterial.

Activation Condition
An activation condition is used for the Aluminum Alloys and Steel Alloys choice lists,
as shown in the figure below.

| 239

The Settings window for the Material combo box is shown below.

Note that the Material combo box uses the material string variable as its source.
The Material choice list is used to define a discrete set of allowed values for the240 |material string variable. The Settings window for the Material choice list is shown

below.

| 241

The Settings window for the Alloy combo box is shown in the figure below.

242 |Note that the Alloy combo box uses both the Aluminum Alloys and the Steel Alloys
choice lists. The choice list for Aluminum Alloys is shown in the figure below.

| 243

The activation condition for the Aluminum Alloys choice list is shown in the figure
below.

U SING A C OMBO B OX TO C HANGE E LEMENT S IZEWhen creating a combo box, you can use the Data Access functionality toreproduce the features of a combo box that exists within the Model Builder. For

244 |example, consider an application where a combo box is used to change theelement size in a mesh, as in the figure below.

Switch to the Model Builder and select the Mesh node (we assume here that themodel has just a single mesh). In the Settings window of the Mesh node, selectUser-controlled mesh (if not already selected). In the Size node, directly under the
Mesh node, select the option Predefined. Click Data Access in the ribbon. This gives
access to the combo box for a predefined element size, as shown in the figure
below.

Select the green check box to the left of the list to make it available as a source for
a combo box in the Application Builder. Then, when you return to the Application
Builder, you will find that the choice list for mesh size is now revealed as apotential Source in the Settings for a new combo box.

| 245

To insert the combo box object, you have two alternatives:• Select Combo Box from the Insert Object menu in the ribbon. In the Settings

window for the combo box, select the node Predefined size (hauto) in the
Source section and then click the Use as Source button.
• In the Editor Tools window, select the node Predefined size (hauto) under the

Mesh > Size node. Then right-click and select Input, as shown in the figure
below.

246 |The corresponding Settings window for the combo box is shown in the figure
below.

Changing the Initial value to From data source ensures that the element size settingof the model, in this case Normal, is used as the default element size in theapplication. The choice list, Predefined size (hauto), from the Model Builder is now
selected as the choice list for your combo box in the Application Builder. This
choice list does not appear as a choice list under the Declarations node of theapplication tree because it is being referenced from the Model Builder. Therefore,
if you want a list with a more limited set of choices, you cannot edit it. Instead,
you have to remove the predefined list as the Source of your combo box and create
a new choice list of your own by declaring it under the Declarations node. For| 247

example, you can create a choice list with three entries, as shown in the figure
below.

To learn which values are used by the Element size list in the model, use Record a
New Method and change the value from Normal to Fine, then to Coarse, and thenback to Normal. Click Stop Recording and read the values in the autogenerated
code. The Element size property name is hauto and the values for Fine, Normal, andCoarse are 4, 5, and 6, respectively, as implied by the automatically generated code
shown in the lines below.
with(model.mesh("mesh1").feature("size"));set("hauto", "4");set("hauto", "6");set("hauto", "5");endwith();The hauto property can also take non-integer values. For more information on
Element size, see “Data Access for Input Fields” on page 104.

U SING A U NIT S ET INSTEAD OF A C HOICE L IST
If the combo box will be used for the purpose of changing units, then a Unit Set
can be used instead of a Choice List (you still select it in the Choice List section of
the Settings window of the combo box).

248 |E qu at ion
An Equation object can display a LaTeX equation by entering the expression in theEnter equation in LaTeX syntax field.

A preview is shown of the rendered LaTeX syntax after leaving the text field.

| 249

Line
Use the Line form object to add a horizontal or vertical line to a form, which canbe used, for example, to separate groups of form objects. For the horizontal line
option, you can also add text that appears within the line.

250 |Web Page
A Web Page object can display the contents of a web page as part of the userinterface.

You can specify the page source in four different ways from the Source list:• Use the default option Page to enter HTML code in a text area below thelist, enclosed by the <html> and </html> start and end tags.
• Use the URL option to link to a web page on the Internet.
• Use the File option to point to a local file resource containing HTML code.

Type the name of the file in the File field or click Browse to locate the file on
the local file system.
• Use the Report option to embed an HTML report. The Browser preview is

not active for this option.

| 251

ImageUse an Image form object to add an image to a form. An image object is different
from a graphics object in that an image object is not interactive. Choose an image
file from one of the library images, accessible from a drop-down list, or by clicking
the Add Image to Library and Use Here button to select a file from the local filesystem. The figure below shows the Settings window for an image objectreferencing the image cube_large.png, defined in the Libraries node.

If you select an image file from your file system, this file will be embedded in theapplication and added to the list of Images under the Libraries node.
While you can change the x- and y-position of the image, the width and height
settings are determined by the image file.
You can paste images from the clipboard to a form window by using
Ctrl+V. For example, you can copy and paste images from thePowerPoint slide presentation software. Such images will be added
automatically to the Images library and embedded in the application. The
names for pasted images are automatically set to: pasted_image_1.png,
pasted_image_2.png, etc.

252 |

VideoA Video object embeds a video file in a form. The supported video file formats are
MP4 (.mp4), OGV (.ogv), and WebM (.webm). However, not all video fileformats are supported on all platforms. When running an application byconnecting to COMSOL Server from a web browser, which formats are supported
depend on the web browser and may vary with different versions of the same webbrowser. When running an application with the COMSOL Client and with
COMSOL Multiphysics, the Internet Explorer version installed on your computeris used as a software component for displaying the video object.
After added to a form, the Video object is represented, in the Form Editor by animage, as shown in the figure below.

The figure below shows the Settings window for the Video object.

The available settings are:
• Show video controls| 253

• Start automatically• Repeat• Initially muted

The option Show video controls enables the video controls such as Play and Stop.
The option Initially muted is intended for the case where you want to play a video
with the sound initially turned off. For example, if the video is set to start
automatically, it can be useful to let the user choose whether the sound should be
on. The user can enable the sound either from the video controls, if the check box
Show video controls is selected, or by right-clicking in the video player.

Pr ogr ess Bar
A Progress Bar object displays a customized progress bar, or set of progress bars,
based on a value that is updated by a method. Use a progress bar to provide
feedback on the remaining run time for an application. The figure below shows
the Settings window of a progress bar object with one progress level.

Note that the built-in progress bar that is visible in the status bar of an applicationis controlled by the Settings window of the Main Window node. By default, thebuilt-in progress bar shows the progress of the built-in COMSOL Multiphysics
core algorithms, such as geometry operations, meshing, and solving. By using the
setProgress method, you can customize the information shown in the built-in

254 |progress bar. For more information, see “Progress Methods” on page 342 and theApplication Programming Guide.
The figure below shows the Settings window of a progress bar object with two
progress levels.

In this example, the progress bar object is part of a form progressform used topresent a two-level progress bar and a message log.
The figure below shows the corresponding progress dialog box in the runningapplication.

| 255

The figure below shows the form progressform.

The code segments below show typical built-in methods used to update theprogress bar and the message log.
// show progress dialog box:
dialog("progressform");
setProgressBar("/progressform/progress1", 0, "Computing prong length.");// code for iterations goes here:
lastProgress = 20;// ...
// update message log:
message("Iteration Number: " + k);message("Frequency: " + Math.round(fq*100)/100.00);
message("Length: " + Math.round(L1*100)/100.00);// update progress bar:
setProgressInterval("Computing frequency", lastProgress,
k*100/MAXITERATIONS);// more code goes here:// ...
// finished iterating:
setProgressBar("/progressform/progress1", 100);
closeDialog("progressform");

In the example above, the central functionality for updating the two levels ofprogress bars lies in the call
setProgressInterval("Computing frequency", lastProgress,
k*100/MAXITERATIONS).

256 |For detailed information on the built-in methods and their syntax, see “Progress
Methods” on page 342 and the Application Programming Guide.

Log
The Log form object adds a log window that displays messages from the built-in
COMSOL Multiphysics core algorithms, such as geometry operations, meshing,and solving.
The Include standard log toolbar check box is selected by default. When selected,
the toolbar in the Log window that you see in the COMSOL Desktop is includedin the application.

The figure below shows a part of an application user interface containing a log
window.

| 257

Me ssage Log
The Message Log object adds a window where you can display messages to informthe user about operations that the application carries out. Implement this featureusing the built-in message method with syntax: message(String message). See
also “GUI-Related Methods” on page 337.

You can also display the value of a variable, for example: message(double
xcoordinate).

The Include standard message log toolbar check box is selected by default. Whenselected, the toolbar in the Messages window that you see in the COMSOLDesktop is included in the application. The Show COMSOL messages check box isselected by default to enable messages from the built-in COMSOL Multiphysics
core algorithms, such as geometry operations, meshing, and solving. Clear the
check box to only allow messages from the application itself. You can include timestamps to message by selecting the check box Add timestamps to messages.

258 |The figure below shows a customized message window with convergence
information from a method (left) and the corresponding Message Log form object(right).

Re sults Ta ble
The Results Table object is used to display numerical results in a table.

The source of the results table data is taken from Results and can be a child nodeof Derived Values, a Table, or an Evaluation Group. In the figure below, a Table node| 259

is used as the source (by selecting this option in the tree and then clicking Use as
Source.)By clearing the check box Show headers, you can choose to hide the column
headers of the results table.

R ESULTS T ABLE T OOLBARThe Include standard results table toolbar check box is selected by default. Whenselected, a toolbar is included that provides the following buttons:• Full Precision• Automatic Notation• Scientific Notation• Engineering Notation• Decimal Notation• Rectangular Complex Numbers• Polar Complex Numbers• Copy Table and Headers to Clipboard• Export

260 |The Export button is used to export to the following file formats:• Text File (.txt)• Microsoft Excel Workbook (.xlsx)- Requires LiveLink™ for Excel®
• CSV File (.csv)• Data File (.dat)

This is shown in the figure below.

C ONTROLLING R ESULTS T ABLES FROM M ETHODS
There is a built-in method useResultsTable() for changing which table is shownin a particular results table form object. For more information on this built-in
method, see “GUI-Related Methods” on page 337.

Form
A form object of the type Form is used to organize a main form in one or more
subforms. To embed a subform, you create a link to it by selecting the form you
would like to link to from the Form reference of the Settings window for the| 261

subform. The figure below shows an example where one of the cells of the form
main has a link to the form input.

The figure below shows the referenced form input.

If you are using grid layout mode, then you can quickly create subforms using theExtract Subform button in the ribbon. See “Extracting Subforms” on page 123.

262 |Form Collection
A Form Collection object consists of several forms, or panes, presented in a mainform. In this example, there are four forms that appear as tabs in a single main
window.

There are four different layout options. From the Type list, choose between:• Tabs, the default setting, which displays the forms using tabbed panes.
• List, which displays a list to the left of the form panes, where you can selectthe form to display.
• Sections, which displays each form in a separate section.
• Tiled or tabbed, which displays the forms in one of two ways depending on

the value of a Boolean variable. For more information, see the description
later in this section.
In the Panes section, in the Use selected forms as panes list, each form represents apane. These will be displayed in the application in the order they appear in the list.
You can change the order by clicking the Move Up and Move Down buttons to theright.
You can control which tab (or list entry) is active by linking to a string variable inthe section Active Pane Selector.
The string variable needs to be equal to one of the form names in the form
collection, such as temperature or conversion in the example above. Otherwise,
it will be ignored.

| 263

If you change the value of the pane selector pane in the above example, in amethod that will be run at some point (a button method, for example), then thepane with the new value will be activated, as shown in the example below.
pane=”conversion”; /* Activate the conversion pane on completion of thismethod */For a form collection with the Type set to Sections, the Active Pane Selector has noeffect. Using an Active Pane Selector is optional and is only needed if you wish tocontrol which tab is active by some method other than clicking its tab. To remove
a string variable used as an Active Pane Selector, click the Clear source toolbar
button under the tree.
The Tiled or tabbed option displays the forms in one of two ways depending on
the value of a Boolean variable used as source in a Tiled or Tabbed section at the
top of the Settings window.

The tabbed mode is identical to a form collection with the Type set to Tabs. In
tiled mode, all the forms are shown simultaneously in a grid. The layout for
the tiled mode can be controlled by the settings in the subsection Tiled modesettings.

264 |Card Stack
A Card Stack is a form object that contains cards. A Card is another type of form
object, one that is only used in the context of a card stack. Flip between cards ina card stack to show one at a time. You associate a card stack with a data sourcethat controls which card to show. Each card specifies a value that is comparedagainst the data source of the card stack. The card stack shows the first card withthe matching value. If no cards match, nothing is shown.

U SING A C ARD S TACK TO F LIP B ETWEEN G RAPHICS O BJECTS
Consider an application where the graphics shown to the user depend on the valueof a scalar variable. This variable may change when a user clicks, for example, aradio button. The variable may also change depending on a computed value; forexample, the value of a Global Evaluation node in the model tree.
The figure below shows the card stack object in the Form Editor.

In this example, the card stack contains cards with graphics objects.

| 265

The figure below shows a card stack Settings window with five cards and a string
variable display as its Active Card Selector.

By clicking a row in the table of cards in the Cards section, followed by clicking
one of the toolbar buttons below the table, you can perform the following
operations on cards:• Delete• Edit• Add Card
• Duplicate

Each row in the table contains the name of the card in the Card column and theirassociated activating values in the Activating value column. The stack decides
which cards to display based on their activating values. In this example, theactivating value is a Boolean variable.

266 |Clicking the Add Card button displays the following dialog box.

By default, the Card type is set to Local, which means that the card is defined locallyin its containing card stack object. If the Card type is set to Existing form, then you
can instead select one of the existing forms. The settings for an Existing form areaccessed directly from the Form Editor by clicking its node or by clicking the Edit
button in the Card section of the corresponding card stack Settings window.
The figure below shows the Settings window of a Card as shown after clicking Editin the table in the section Cards.

| 267

To access locally defined cards, right-click the card stack in a form window to
select between the different cards in the card stack, as shown in the figure below.

From this menu, you can also duplicate cards.
To edit cards, you can also use Alt+Click, which opens a dialog box that lets you
select multiple cards at once.

268 |The figure below shows card1 of the card stack resultsCardstack with agraphics form object.

In the Position and Size section you can change the alignment and size of the card
stack and cards.

When selected, the check box Adjust size to selected card makes it possible to havethe card stack adjust its size to the currently selected card. When not selected, thecard stack will be as large as the largest card, regardless of which card is selected.
Before version 5.6, the card stack always took the size of its largest individual card,
which meant that even small or empty cards still took up space in the layout. Now,

| 269

when a card is empty, the card stack will disappear, which is a desirable feature inmany cases. Using it you can for example have a dynamic documentation card
stack appear and disappear depending on the user’s actions.

File Import
A File Import object is used to display a file browser with an associated input field
for browsing to a file or entering its path and name. It is used to enable file importby the user of an application at run time, when the file is not available in theapplication beforehand.
Consider an application where a CAD file can be selected and imported at run
time, as shown in the figure below.

The corresponding File Import object is shown in the figure below.

270 |The Settings window for the File Import object has a section File Destination. In thissection, you can select any tree node that allows a file name as input. This is shownin the figure below, where the Filename for a geometry Import node is selected.

In this application, the File types tablespecifies that only CAD files are allowed.
You can further control which File types areallowed by clicking the Add and Delete
buttons below the list of File types. Clicking
the Add button displays the dialog box
shown to the right:| 271

A LTERNATIVES TO U SING A F ILE I MPORT O BJECT
If an input field for the file path and name is not needed, then there are othermethods for file import that allow a user to pick a file in a file browser. For
example, you can use a menu, ribbon, toolbar item, or a button to open a filebrowser. The figure below shows the Settings window of a button used to importa CAD file.

A File Import object can also reference a File declaration. For more information, see“File” on page 158. For more information on file handling in general, see“Appendix C — File Handling and File Scheme Syntax” on page 307.
The built-in method that corresponds to the command Import file is importFile.
For example, for importing an image you can use:
success=importFile("file1",newString[]{"ALL_IMPORTABLE_IMAGES","PNG","JPEG","BMP","GIF"});

272 |Information Card Stack
An Information Card Stack object is a specialized type of Card Stack object used todisplay information on the relationship between the inputs given by the user to an
application and the solution. The figure below shows a portion of a runningapplication in which an information card stack is used together with informationon the expected computation time.

The corresponding form objects are shown below:| 273

The figure below shows the Settings window where a string variable
solution_state is used as the source.

There are similarities with a Card Stack object, but for the Information Cards, eachcard has an icon and text. In the figure above, the string variable values
nosolution, inputchanged, and solutionexists control which information
card is shown.

274 |In this example, the information card stack is accompanied by a data display object
where a model tree information node for the Expected Computation Time is usedas the source. The figure below shows its Settings window.

Note that information nodes in the model tree are only shown when working with
the Application Builder. They are made available in the Source section in the
Settings window for form objects, when applicable.
You can also find information nodes with Last Computation Time under each study.
The information node Last Computation, found directly under the Model node, willcorrespond to the computation time for the last computed study.
Information nodes can be used as a source for input field objects, text objects, anddata display objects. For input field objects and text objects, in order for the
information nodes to be accessible, the Editable check box has to be cleared.

| 275

The Expected Computation Time take its data from the root node of the application
tree, as shown below.

If the computation time is predominantly spent in a method, such as when thesame study is called repeatedly, then you can manually measure the computation
time by using the built-in methods timeStamp and setLastComputationTime.
For more information, see “Date and Time Methods” on page 342.

Array Input
An Array Input object has an input table used to enter array or vector-valued input
data. An array input object supports string arrays as data sources. You can add an
optional label, symbol, and unit.

276 |U SING AN A RRAY I NPUT O BJECT FOR 3D P OINT C OORDINATE I NPUT
Consider an application where the user enters 3D coordinates for a point where
the stress is evaluated. The figure below shows a screenshot from an application
with an array input, button, text label, and data display object.

| 277

The figure below shows the Settings window of the array input object.

278 |The Array Input form object uses a Source named samplecoords, which is a 1D
Array of type Double. This array is created prior to the creation of the Array Input
object by declaring an Array 1D Double with the following Settings.

In the Settings window of the array input object:• In the Length field, enter the length of the array as a positive integer. The

default is 3.
• From the Show vector as list, choose Table (the default) to show the arraycomponents as a table, or choose Components to show each array component
as a separate input field with a label.
• In the Value table, enter the initial values for the components in the array.
• The Layout Options section provides settings for adding optional labels andunits to the array input.
In this example, when the user clicks the button labeled Evaluate stress at point,
the following method is run:with(model.result().dataset("cpt1"));set("pointx", samplecoords[0]);set("pointy", samplecoords[1]);set("pointz", samplecoords[2]);endwith();where the values pointx, pointy, and pointz will be used subsequently as
coordinates in the evaluation of the stress.

| 279

Radio Button
A Radio Button object has a fixed number of options from which you can choose
one. It is most useful when you have just a handful of options.

U SING R ADIO B UTTONS TO S ELECT A L OAD
Consider an application where the user can select one of three predefined loads,
as shown in the following figure.

280 |The corresponding Settings window is shown below, where the global parameter
F is used as the source.

The Orientation can be set to Vertical (default) or Horizontal.
In the Initial value list, choose the manner in which the initial selection of the radio
button should be made. The options are From data source, First allowed value (thedefault), and Custom value. For the Custom value option, select from a list of theallowed values given by the choice list.
In the Choice List section, you can add choice lists that contribute allowed values
to the radio button object, where each valid value represents one radio button.

| 281

The radio button names are taken from the Display name column of theirassociated choice list. The figure below shows the choice list used in this example.

U SING A U NIT S ET INSTEAD OF A C HOICE L IST
If the radio button will be used for the purpose of changing units, then a Unit Set
can be used instead of a Choice List (You still select it in the Choice List section of
the Settings window of the radio button object).

Selection Input
In the Application Builder, you can allow the user of an application to interactively
change which entities belong to an Explicit selection with a Selection Input object
or a Graphics object. For more information on selections, see “Selections” on page88.
You can choose to use a graphics object as the source of a selection without
having any selection input object. You can also link both a graphics object
and a selection input object to the same explicit selection.

282 |In the example below, the embedded model has a boundary condition definedwith an Explicit selection. Both a Selection Input object and a Graphics object areused to let the user select boundaries to be excited by an incoming wave.

The user can select boundaries here by clicking directly in the graphics window
corresponding to the Graphics object or by adding geometric entity numbers in alist of boundary numbers corresponding to a Selection Input object.
To make it possible to directly select a boundary by clicking on it, you can link agraphics object to an explicit Selection used to group boundaries, as shown in the
figure below. Select the explicit selection and click Use as Source.

| 283

In the figure below, there are two explicit selections, Excitation Boundary and Exit
Boundary, and the graphics object graphics2 is linked to the selection Excitation
Boundary.

When a graphics object is linked directly to an explicit selection in this way, thegraphics object displays the geometry and the user can interact with it by clicking
on the boundaries. The boundaries will then be added (or removed) to thecorresponding explicit selection.

284 |To make it possible to select by number, you can link a selection input object toan explicit selection, as shown in the figure below.

In a selection input object, you can copy, paste, remove, clear, and zoom into
selections.
You can have events associated with selections. The On data change event will be
triggered when the selection is changed. If you have a local method associatedwith this event, you will get a method with an integer array argument. The
method is called with the new entities of the selection. The On activate event willbe triggered when the Activate Selection button is clicked.

| 285

Text
A Text object is a text field with default text that is taken from a string variable oran Information node. The Settings window for a text object is shown below.

Select a string variable or Information node from the tree in the Source section andthen click Use as Source. In the Value field, enter the initial text. By default, theInitial value text is taken from this field. To instead use the string variable for theInitial value text, change the Initial value setting to From data source.
The check box Editable is cleared by default. If selected, the text object can beused, for example, to type comments in a running application. If the text ischanged by the user, it is stored in the string variable that is used as the data
source, regardless of the Initial value setting.
The check box Wrap text is selected by default. Clear this check box to disable
wrapping of the text. A scroll bar appears if the text does not fit.
For more information on Information nodes, see “Data Display” on page 101.

286 |Lis t B o x
A List Box object is similar to a radio button object, except that it allows for thesimultaneous selection of multiple options.

U SING A L IST B OX TO S UPERIMPOSE V IBRATIONAL M ODES
Consider an application where the first six vibrational modes of a mechanical partcan be superimposed and visualized by selecting them from a list box, as shown in
the figure below.

As an alternative, the following figure shows that a list can be displayed as a dialog
box.

| 287

The Settings window for the list box of this example is shown in the figure below.

The Select values in list allows you to choose between two alternatives, List box or
Dialog, for displaying the list.
You can use any scalar or array declaration as a source. Select from the tree andclick Use as Source. If you use a string array as the source, you can, in the runningapplication, select more than one item in the list using Shift+Click or Ctrl+click.

288 |For other sources, you can only select one value from the list. This example uses a
1D string array svar1D. Its Settings window is shown below.

In the Choice List section, you can add choice lists that contribute allowed values
to the list box. The figure below shows the choice list used in this example.

The vibrational modes 1–6 correspond to trivial rigid body modes and are not ofinterest in this application, hence the Value column starts at 7. The choice list
allows you to hide the actual mode values in the model from the user by only
displaying the strings in the Display name column. The first nonrigid body modes
are named Mode 1, Mode 2, etc.
The method below uses the COMSOL Multiphysics operator with() to visualize
the superimposed modes. This example is somewhat simplified, since it ignores theeffects of amplitude and phase for the modes.
String withstru="0";String withstrv="0";String withstrw="0";| 289

for(int i=0;i<svar1D.length;i++){withstru=withstru + "+" + "with(" + svar1D[i] + ",u)";withstrv=withstrv + "+" + "with(" + svar1D[i] + ",v)";
withstrw=withstrw + "+" + "with(" + svar1D[i] + ",w)";}
with(model.result("pg7").feature("surf1").feature("def"));setIndex("expr", withstru, 0);
setIndex("expr", withstrv, 1);
setIndex("expr", withstrw, 2);
endwith();useGraphics(model.result("pg7"),"/form1/graphics8");
zoomExtents("/form1/graphics8");

Assuming the user selected the modes 1, 3, and 5 by using the list box, the method
creates an expression with(1,u)+with(3,u)+with(5,u). This expression is thenused for the x-displacement (dependent variable u) in a displacement plot. In asimilar way, the method automatically creates expressions for the variables v and w
associated with the y- and z-displacement, respectively. Note that the commandwith(), used in the results in the example above, is different from the built-in
with() command used to shorten syntax that is described in “With, Get, and Set
Methods” on page 346.

U SING A U NIT S ET INSTEAD OF A C HOICE L IST
If the list box will be used for the purpose of changing units, then a Unit Set canbe used instead of a Choice List (You still select it in the Choice List section of theSettings window of the list box).

290 |TableA Table Object represents a table with rows and columns that can be used to define
input or output. The figure below shows an example of a running application witha table object used to accept input in three columns.

The figure below shows the corresponding form object and its Settings window.

In this example, the data source references three 1D string arrays. You can selectany type of array as the source and then click Use as Source.

| 291

Three check boxes control the overall appearance of the table:• Show headers• Automatically add new rows
• Sortable

The Automatically add new rows check box ensures that an additional empty row
is always available when a user is filling out a table. If all of the 1D string arrays,
which are used as a source to the table, have nonempty values for New element
value in their declaration Settings window, then this functionality is deactivated. In
this case, new rows can only be added by clicking the Add button in the associatedtable toolbar, if such a button has been made available.
The Sortable check box makes it possible to sort the table with respect to aparticular column by clicking the corresponding column header.
The Sources section contains a table with five columns:• Header• Width• Grow• Editable• Alignment• Data source

Each row in this table defines a column in the table object. The option Grow allows
individual columns to grow when a form is resized. This option is only applicableto grid mode and if the Horizontal alignment of the table is set to Fill.

292 |In the example, the string arrays define the initial values for the rows
corresponding to the three columns, as shown in the figure below:

T OOLBARIn this section, you can select which toolbar items (buttons) should be used tocontrol the contents of the table. The Position list defines the location of thetoolbar relative to the table and provides the following options:• Below• Above• Left• Right

The Icon size setting allows you to choose Small or Large icons.
To add an item to the toolbar, click the Add Toolbar Item button below the table.

| 293

The following dialog box is then shown.

You can add the following items:• Save to File
• Move Up• Move Down
• Add
• Delete• Clear Table• Clear Table and Load from File
• Load from FileIn addition, you can add customized items by clicking Custom Item or Custom
Toggle Item in the Toolbar Items dialog box. The figure below shows the Edit
Custom Toolbar Item dialog box used to define a customized button. The dialog

294 |box has two tabs for a regular item and three tabs for a toggle item. In this case,the button Process 1 is used to set default values for a certain process.

The Choose commands to run tab is similar to that of menu, ribbon, and toolbar
items, as well as buttons.
The Load from File and Save to File buttons are used to load and save from/to thefollowing file formats:• Text File (.txt)• Microsoft Excel Workbook (.xlsx)- Requires LiveLink™ for Excel®
• CSV File (.csv)• Data File (.dat)

This is shown in the figure below.

The allowed separators are comma, semicolon and tab for CSV files, and space andtab for DAT and TXT files.

| 295

Slider
A Slider is a form object for choosing numerical input using a slider control.

U SING A S LIDER TO C HANGE THE M AGNITUDE OF A S TRUCTURAL L OAD
Consider an application where the magnitude of a load can be changed by a slider
control, such as in the figure below.

In this example, the slider is accompanied by an input field that is used to display
the selected value.

296 |The Settings window of the slider is shown in the figure below.

In this example, the slider uses a global parameter F as its source. You can selectany parameter, variable, or declared scalar variable as a source. Select from theapplication tree and click Use as Source.
You determine the range of values for the data source by defining the Minimum
value, Maximum value, and Number of steps for the slider. The Orientation can be
Horizontal or Vertical. You can also set a Tooltip that is shown when hovering overthe slider. The Append unit to number option lets you associate a unit with theslider. This unit is appended to the number using the standard bracket notation,such as [N], before being passed as a value to the source variable. In the example
above, the input field and the slider both have the setting Append unit to number
activated. As an alternative to Append unit to number, you can choose Append unit
from unit set. See “Unit Set” on page 159 for more information.

| 297

In the Initial value list, select From data source or Custom value for the initial value
for the slider.
In the Events section, in addition to specifying which method to call for an On datachange event, you can select the check box Trigger while dragging. This setting
determines if the event method should be called continuously while the slider isbeing dragged or only upon its release.

This setting can be useful if the method that is called by the On data change event
is computationally heavy, so that there is a lag when dragging the slider.

Knob
A Knob is a form object for choosing numerical input using a control knob, similar
to a slider.

U SING A K NOB TO C HANGE THE A NGLE OF A C RANE A RM
Consider an application where the angle of a truck mounted crane arm can bechanged by control knobs, such as in the figure below.

In this example, the knobs are accompanied by input fields that are used to display
the selected value.

298 |The Settings window of one of the knobs is shown in the figure below.

In this example, the knob uses a string variable Angle1 as its source. You can selectany parameter, variable, or declared scalar variable as a source. Select from theapplication tree and click Use as Source.
You determine the range of values for the data source by defining the Minimum
value, Maximum value, and Number of steps for the slider.
The Mouse movement can be Distance, Vertical, or Circular. Distance changes thevalue with a linear mouse movement in any direction. Vertical changes the value
when you move the mouse vertically. Circular changes the value when you make acircular mouse movement. A physical control knob is usually controlled with acircular movement. However, when using a mouse this is usually not the mostconvenient way. Instead, use a linear mouse movement by selecting Distance or
Vertical.
You can also set a Tooltip that is shown when hovering over the knob. The settings
for units are similar to that of a slider.
In the Initial value list, select From data source or Custom value for the initial value
for the knob.

| 299

In the Events section, in addition to specifying which method to call for an On datachange event, you can select the check box Trigger while dragging. This setting
determines if the event method should be called continuously while the knob isbeing dragged or only upon its release.

This setting can be useful if the method that is called by the On data change event
is computationally heavy, so that there is a lag when dragging the knob.

Hyperlink
A Hyperlink object embeds a hyperlink in a form. The figure below shows anexample of a hyperlink.

300 |The figure below show the corresponding Settings window.

The Hyperlink object supports the types of URLs that you can use in a web
browser, including:• Web Page: When a user clicks the hyperlink for a web page, it opens in theuser’s default browser. The URL string needs to be on the form
protocol://address, where protocol is the transmission protocol; forexample, HTTP or HTTPS. The web address can be partial or complete, but
it is recommended to use a complete web address.
• Email: An email address is specified on the form mailto:emailaddress. This

will launch the user’s default email application program and prepare a newmessage where the To field is set to the address specified. This way ofinteractively sending an email from a COMSOL application is different fromusing the built-in method. For more information on the built-in methods
for email, see “Email Methods” on page 334.

| 301

Toolbar
A Toolbar object contains the specifications of a toolbar with toolbar buttons. The
figure below shows a toolbar with buttons for Save as, Compute, and Plot.

The Settings window for this toolbar is shown in the figure below.

Each row in the Toolbar Items table contains either an Item or Toggle Item
corresponding to a toolbar button or toggle button, respectively, or a Separator.
Use the buttons below the table to add items or separators, change the row order,
or delete a row. Click the Edit button to display the Settings window associated302 |with each row. The figure below shows the Settings window of item1, the Save As
item.

The text in the Tooltip field will be shown as a tooltip when hovering over the
toolbar button. The text in the Text field will be shown next to the icon, if any;otherwise just the text is shown. The Icon list, the Keyboard shortcut field, and theChoose commands to run tree represent the same functionality as a button object.
For more information, see “Button” on page 63.

SpacerA Spacer object is invisible in the user interface and is only used when working in
grid layout mode. It defines a space of fixed size that you can use to ensure thatneighboring form objects have enough space to show their contents. Typically,
you would use a spacer next to a table or graphics object to ensure that they are
rendered properly. If the user resizes the window so that it becomes smaller than

| 303

the size of the spacer, the effective size of the window is maintained by displaying
scroll bars. The figure below shows the Settings window of a spacer object.

304 |Appendix B — Copying Between Applications
Many nodes in the application tree can be copied and pasted between applications,
including: forms, form objects, menu items, methods, Java utility methods,
external libraries, file declarations, choice list declarations, menus, menu items,
ribbon sections, ribbon tabs, and ribbon items.
When you copy and paste forms, form objects, and items between applications, thecopied objects may contain references to other objects and items. Such references
may or may not be meaningful in the application to which it is copied. The
following set of rules apply when objects are pasted from the clipboard:• A declaration referenced in a form object or menu item is included when

copying the object, but is not necessarily pasted. It is only pasted if there isno compatible declaration present. If a compatible declaration exists, that isused instead. A compatible declaration is defined as one having the same
name and type. For example, a string declaration is not compatible with an
integer declaration. An existing declaration may have an invalid default, but
no such check is done when pasting.
• A referenced global parameter may have a different unit, but will still beconsidered compatible.
• A form or form object directly referenced from another form object is notincluded automatically when copying objects. The direct reference will point
to an existing object if it has the same name. If the original reference isamong the copied objects, then that object will be used in the reference
instead of any existing objects having the same name. The name of thecopied reference will be changed to avoid name collisions.
• No objects in the model tree will be automatically copied, for example, agraphics object referring to a geometry or an input field referring to a
low-level setting exposed by Data Access. If the reference points to an object
that exists in the model tree of the target application, then that reference will
be used.
• References to nonexisting objects will be attempted to be removed when

pasted. An exception is command sequences in buttons, where all commands
are kept and marked as invalid if they point to a nonexisting reference.
• Local methods are included in the copy-paste operation. However, noattempt is made to update the code of the method. This also applies when
copying a global method.
• Arguments to commands in the command sequence of a button or a menu

item will be left as is.

| 305

• All image references are automatically copied and added to the image librarywhen applicable. If there is an existing image with the same name, it will be
used instead of the copied version.
• No files, sounds, or methods are automatically copied if referenced to.

However, methods can be copied and pasted manually.
• All pasted objects that have a name that conflicts with that of an existing

object will be renamed. Any references to the renamed object from otherpasted objects will be updated.

306 |Appendix C — File Handling and File Scheme Syntax
The handling of files may be an important feature of an application. For example,
the application may require a spreadsheet file with experimental data as input, a
CAD file to be imported, or a report to be generated and exported. The
Application Builder provides tools for reading and writing entire files or portionsof a file. The way that this is done will vary depending on the system where theapplication is running. The file system may be different on the computer running
COMSOL Multiphysics, where the application is developed, and on the computer
where COMSOL Server is installed and the application will run once it isdeployed. For more in-depth information on reading and writing various types ofdata to file, see the Application Programming Guide.

File Handling with COMSOL Server
In general, you cannot read and write files to local directories when runningapplications with a web browser or the COMSOL Client for Windows. The
application and its methods are run on the server and have no knowledge of theclient file system (where the web browser or COMSOL Client is run).
However, there are techniques for transferring files to and from the client filesystem when running an application both with a web browser and the COMSOLClient.
A File Import object can be used to ask the user for a file. The user then browses
to a file on the client file system, which is then uploaded to the COMSOL Server
file system and becomes available to the application and its methods. This can beused, for example, to provide a CAD file or an experimental data file from the user
at run time. This is covered in the section “File Import” on page 312.
In a command sequence of, for example, a button, you can export data generated
by the embedded model by running a subnode of the Export or Report nodes. Thisis covered in the section “File Export” on page 319.

| 307

S AVING AND O PENING F ILES USING F ILE C OMMANDSIn the editor tree used in a command sequence, the File Commands folder contains
commands to save and load applications and files, as well as exiting an application.

The command Open File will pick any file from the server produced by a method,
the model, or embedded with the application, and open it using the associatedapplication on the client. This can be used, for example, to open a PDF file in theclient file system, or show a text file or an image exported from the model on theclient side. In the figure above, an Open File command is used to open the PDF
documentation for an application. The corresponding PDF file is embedded in theapplication by being stored in the Libraries > Files node. Files located there arereferenced using the embedded:/// file scheme syntax described in the next
section, “File Scheme Syntax” on page 310.

308 |To open files from a method, use the built-in method fileOpen; see also
“Operating System Methods” on page 334.
To save a file, use the command Save File As, which is similar to Open File. It willtake any file from the server file system and display a Save As dialog box to the user
where the user can browse to a client location to save the file. This is similar to
downloading files from a link within a web browser. In the figure below, a Save
File As command is used to save a CAD model that is stored in the Libraries > Filesnode.

To save files from a method, use the built-in method fileSaveAs; See also “GUICommand Methods” on page 340. For more information on saving and exporting
files, see “File Export” on page 319.
The Save Application and Save Application As commands are available for use in thecommand sequence for certain form objects. The Save Application As command
will display a Save As dialog box where the user can specify a client path where theentire application will be saved.
Similarly, the Save Application on Server and Save Application on Server As
commands are available to save the entire application on the server file system. For
information on the corresponding built-in methods, see “GUI Command
Methods” on page 340.
In summary, both uploading and downloading files from the client file system is
supported, but, due to web browser and system security settings, the application
can never do it silently in the background without the user browsing to the sourceor destination location of the file.

| 309

M ODEL C OMMANDSIn the editor tree used in a command sequence, the Model Commands folder
contains two commands: Clear all solutions and Clear all meshes. Use thesecommands to make the MPH file size smaller before saving an application byerasing solution and mesh data, respectively.

File Scheme Syntax
To make applications portable, the Application Builder allows you to use virtual
file locations using file schemes. A file scheme can be seen as a pointer to a file on
the file system, but the application does not need to know where the file is actuallystored (this is set in the Preferences dialog box, see below.)
Different file schemes exist for different purposes:• The user file scheme is for files that should be persistent between different

runs of an application by the same user.
• The common file scheme behaves in the same way, but is for files that should

be shared between all users.
• The temp file scheme is for files that should be removed as soon as theapplication is closed.

310 |• The embedded file scheme is used to store files in the application itself. Thiscan be useful if you want to make the application self-contained and send it
to someone else.
• The upload file scheme is for files that are uploaded to the application by theuser at runtime, such as a CAD-file to which the user browses.
The table below summarizes all available file schemes.
SCHEME

REFERS TO

DEFAULT PATH

TYPICAL USAGE

embedded:///Files embedded in
the application using
Libraries > Files

N/A

Experimental data,
CAD files, mesh files,
interpolation data

upload:///Files to be uploadedby the user at run
time

Determined by theTarget directory in
the Settings windowof the File declaration

Experimental data,
CAD files, mesh files,
interpolation data

temp:///

Files in a random
temporary directory,
which is unique foreach started
application instance.
These files aredeleted when theapplication is closed.

A random
subdirectory to thefolder for temporary
files, as determinedby the settings in
Preferences > Files

Temporary files
produced bycommand sequences
or methods, or data
export to a file savedon the client (for use
with COMSOL
Server)user:///

Files in a directory
shared by all
applications for thecurrent user

Determined by thesettings in
Preferences > Files

Output frommethods to be saved
between sessions

common:///Files in a directory
shared by all users

Determined by thesettings in
Preferences > Files

Files shared between
many users orapplications

For more information on files in the Libraries node accessible by theembedded:/// syntax, see “Libraries” on page 217.
The table below summarizes the usage of the different file schemes. In the table,
a check mark means that this scheme is available and (r) means that it is therecommended scheme.
USAGE

EMBEDDEDUPLOAD

File is used as input

(r)



File is output
Method reading a file

(r)



TEMP

USER

COMMON


(r)









| 311

USAGEEMBEDDEDUPLOAD

Method writing a file
File is client-side





TEMP

USER

(r)



(r)



COMMON

You can set the preferences for the paths to temporary, user, and common files in
the Files page of the Preferences dialog box, which is accessible from the File menu,
as shown in the figure below.

File Import

CAD I MPORT USING THE M ODEL T REE AND A F ILE I MPORT O BJECT
A File Import object is used to display a file browser with an associated input field
for browsing to a file or entering its path and name. It is used to enable file importby the user of an application at run time, when the file is not available in theapplication beforehand. You can directly link a File Import object to a file Importnode in the model tree; for example, a CAD Import node. Consider an application

312 |where a CAD file can be selected and imported at run time, as shown by the figure
below.

The corresponding File Import object is shown in the figure below.

The Settings window for the File Import object has a section File Destination. In thissection, you can select any tree node that allows a file name to be input. This isshown in the figure below, where the Filename for the Import node is selected.

| 313

If you do not wish to use a File Import object, you can directly reference a Filenamefrom a button or an item in a menu, ribbon, or toolbar, or alternatively create amethod that calls the built-in method importFile as an event, for example
importFile("file1");

assuming there is a file declaration file1.
The figure below shows a ribbon item used for geometry import together with its
Settings window.

314 |In the Settings window above, the command Import file to Import 1 will open a filebrowser for the user to select a file, as shown in the figure below.

The subsequent commands build and plot the geometry, zoom out using zoom
extents, and finally set the value of a string variable (in this case used to control acard stack).
For more information on the File Import object, see “File Import” on page 270.

F ILE I MPORT IN M ETHODSContinuing the example of the previous section, assume that we click Convert to
New Method in the Settings window. The corresponding lines of code show how
CAD import can be accomplished from a method:
importFile(model.geom("geom1").feature("imp1"), "filename");model.geom("geom1").run();useGraphics(model.geom("geom1"), "form1/cardstack1/card3/graphics1");
zoomExtents("form1/cardstack1/card3/graphics1");
mode = "Visualization";

The first line illustrates using the built-in method importFile. For more
information on the method importFile and other methods for file handling, see“File Methods” on page 332 and the Application Programming Guide.

F ILE A CCESS AND F ILE D ECLARATIONSAt the bottom of the Settings window of a File Import object, you can see which
file scheme syntax to use to access an imported file from a method (next to Access| 315

using:). The figure below shows an example where a File Destination and Filename
are used.

The file scheme syntax, upload:///geom1/imp1/filename, needs to be usedwhenever accessing this file.
As an alternative, you can use a File declaration under the Declarations node.
(However, File declarations are primarily used for file import from method code.)In this case, the file chosen by the user can be referenced in a form object or
method using the syntax upload:///file1, upload:///file2, etc. The file namehandle (file1, file2, etc.) can then be used to reference an actual file namepicked by the user at run time. See also “File” on page 158.
This syntax can also be used in any file browser text fields within the Model
Builder nodes. The figure below shows a file reference used in the Filename fieldof the Import model tree node for a model using geometry import.

However, a quicker way is to link a file import object directly to the Filename field,
as described previously in the section “CAD Import using the Model Tree and aFile Import Object” on page 312.

316 |

I MPORTING E XPERIMENTAL D ATA
Consider an application where the user is providing a file with experimental data
at run time. The figure below shows the file import object of such an application
as it appears in grid layout mode.

The figure below shows the Settings window of the corresponding file importobject and its link to a file declaration.

| 317

In this application, the File types table specifies that only CSV files are allowed. The
Settings window for the File declaration is shown in the figure below.

The file declaration serves as the “destination” of the imported data, which is
written to the file upload:///experimental.csv.
Note that the file extension .csv used in the declaration is optional and that thefile picked by the user at run time can have any name. For example, the file namepicked at run time can be my_data.csv, but when referenced in method code, theabstract file handle name experimental.csv is always used.
In order to make it possible to run the application without having to first provide
experimental data, a file containing default experimental data is embedded in theapplication. This default data file is used by the application by accessing it with theembedded:/// file scheme syntax, as shown in the figure below.
In this example, which uses the Optimization Module, the application performs aleast-squares fit to the experimental data.

318 |The following method handles the logic to determine if user-provided
experimental data files exist or if the default data set should be used.
if (exists("upload:///experimental.csv")) {with(model.physics("opt").feature("glsobj1"));set("fileName", "upload:///experimental.csv");
endwith();}else{
String s_data = confirm("No experimental data file was uploaded. Do you
want to use the embedded data?", "Experimental Data", "Yes", "Cancel
Parameter Estimation");if(s_data.equals("Cancel Parameter Estimation")){return;}}If a user-provided file exists, the code replaces
embedded:///experimental_default.csv with upload:///experimental.csv
in the physics interface glsobj1.
More information on file import can be found in the Application Programming
Guide.

File Export

F ILE E XPORT USING THE M ODEL T REE
In a command sequence of, for example, a button, you can export data generated
by the embedded model by running a subnode of the Export or Report nodes.
In the model tree, the Export node may contain several types of subnodes for fileexport, including:• Data• Plot• Mesh• Table• 3D Image• 2D Image• 1D Image• Animation| 319

The Settings window for each of these nodes contains an Output section with afield for Filename. The figure below shows the Settings window for an Export > Plotnode.

You can leave the Filename field blank, as shown in the figure above. In thecommand sequence of, for example, a button, you can run the corresponding
Export > Plot node and, at run time, it will open a file browser window for the user
to select a location and file name, as seen in the figure below.

While developing an application, you may need to use the Model Builder
repeatedly to check the exported data. In this case, you can use the Filename field
for a test file and, by selecting the Always ask for filename check box, a file browser
will still be opened at run time.

320 |In a similar way to the Export subnodes, each Report subnode has a Format section
with a Filename field, as seen in the figure below.

By running a Report subnode, a file browser window is opened for the user toselect a location and file name for the report.
For more detailed control over file import and export, you can instead use a file
scheme.

F ILE E XPORT U SING A T EMPORARY F ILE
Some applications may need to produce temporary files, and this is accomplishedby using the temp:/// file scheme. The temporary files are stored in a random
temporary directory, which is unique for each started application instance. Thesefiles are deleted when the application is closed. Temporary files can be producedby command sequences or methods, or output to be saved on the client when usedwith COMSOL Server.

| 321

The example below shows the Settings window of an Export > Plot node that isused to export plot data as numerical values.

The Filename in its Output section is set to temp:///lineplot.txt.
To make it possible to save the plot in this example, a button is created. In the
Settings window for the button, in the section Choose Commands to Run, first create
the output graph file by choosing the Export > Plot node created above andclicking Run. Second, choose GUI Commands > File Commands > Save File As andclick Run again.

322 |In the Output section of the button Settings, set the filename to the name of thetemporary file created by the Export Plot command, in this case,
temp:///lineplot.txt.

| 323

The Save File As command provides a dedicated Edit Argument dialog box
with easy access to all embedded files as well as shortcuts for all file
schemes.

The corresponding method code is as follows:model.result().export("plot1").run();fileSaveAs("temp:///lineplot.txt");

The Use of Temporary Files for File Export
Note that as a first step, in the example above, the file is written to a temporary
file, using the call to model.result().export("plot1").run(). This step isdone automatically by the application. In the second step, the method
fileSaveAs opens a file browser and lets the user of the application choose the filelocation, for example, a folder on the computer’s local file system or to a network
folder. This extra step is needed in order for the application to function in a web
browser. Due to the security settings of a typical web browser, the application is
not permitted to automatically save a file to an arbitrary location. Instead, theapplication is allowed to save to a few specific locations including the temp folder,
whose location is specified in the Preferences dialog box settings. The otherlocations are the user and common folders, also specified in the Preferences settings.
For more examples of file export, see the Application Programming Guide.

C REATING R EPORTS USING L OW -L EVEL F UNCTIONALITY
This section describes creating reports using low-level functionality. For a more
direct method, see “File Export” on page 319.

324 |

The example below shows an application where a report in the Microsoft Word
format (.docx) can be saved by the user. The figure below shows a tab in the
ribbon of the application. In this tab, there is a Report button in the Documentation
section.

The associated application tree node is shown in the figure below.

| 325

The following figure shows how the syntax user:/// was used in the Filename
field in the Settings window of the Report node of the Model Builder.

In this application, the check box Open finished report is selected, which meansthat the Word document will open after the report has been created. The user of
the application can then save the report from the Word file menu.
In this example, the file scheme common:/// could have been used in the sameway. The user and common file schemes are primarily useful when the same files
are used repeatedly by an application.

326 |The figure below shows the Settings window of the Report ribbon item.

The method createReport includes the following call:model.result().report("rpt1").run();

The file scheme syntax can also be used directly in methods. The code below isfrom a method used to export an HTML report.
String answerh = request("Enter file name","File Name", "Untitled.html");if(answerh != null){model.result().report("rpt1").set("format","html");model.result().report("rpt1").set("filename","user:///"+answerh);model.result().report("rpt1").run(); }}| 327

Appendix D — Keyboard Shortcuts
The table below lists the keyboard shortcuts available in the Application Builder.
SHORTCUTACTION

Ctrl+A

Select all

Ctrl+D

Deselect all

Ctrl+C

Copy

Ctrl+V

Paste

Ctrl+XCutDel

APPLICATIONBUILDERFORMEDITORMETHODEDITOR
























Delete

Ctrl+N

Create a new application







Ctrl+S

Save an application







Ctrl+F8

Test an application







Alt+Click

Edit certain form objects



Ctrl+Pause

Stop a method

Ctrl+Shift+F8

Apply changes



Ctrl+R

Record code

F11

Go to node

Ctrl+K

Create shortcut







F1

Display help







F2

Rename applicable nodes

F3

Disable applicable nodes

F4

Enable applicable nodes

Ctrl+Up arrow

Move applicable nodes up

Ctrl+Down arrow

Move applicable nodes down

Ctrl+Z

Undo







Ctrl+Y

Redo (Control+Shift+Z on Mac)





F5

Continue (in debugger)



F6

Step (in debugger)

F7

Step into (in debugger)

F8Compile Application/Create Add-in

F9Check syntax

328 |










SHORTCUT

ACTIONAPPLICATIONBUILDER

Ctrl+F

Find and replace text in methods

Ctrl+Space, Ctrl+/,or Ctrl+OEM2

Autocomplete method code

Ctrl+U

Make selected code lowercase



Ctrl+Shift+U

Make selected code uppercase



Ctrl+B

Toggle breakpoint on selected line

Ctrl+M

Toggle between matching
parentheses, square brackets, or
curly braces

Ctrl+Shift+M

Select all characters between
matching parentheses, square
brackets, or curly braces

Ctrl+Scroll wheelup

Zoom in, in method code window

Ctrl+Scroll wheel
down

Zoom out, in method code window

Ctrl+All arrow keys

Fine-tune position of selected form
objectsAll arrow keys

Fine-tune position of selected form
objects

Ctrl+Shift+A

Go to Application Builder window

Ctrl+Shift+M

Go to Model Builder

Ctrl+Alt+Left-click

Create a local method or open amethod associated with a form
objectCtrl+Alt+
Double-click

Open a method from Method
Editor code

Alt+F4Close window

Ctrl+F4
Ctrl+Shift+F4

FORM
EDITORMETHODEDITOR










Close document



Close all documents

Ctrl+7

Toggle comment on and off

Press Ctrl andleft-click. While
holding down the
key and button, dragthe mouse.

Copy form object






| 329

330 |

Appendix E — Built-In Method LibraryThis appendix lists all of the built-in methods available in the Method Editor,
except for methods that operate on the model object and the application object.
For detailed information on using the built-in methods and for full informationon the syntax used, see the Application Programming Guide and theProgramming Reference Manual.
As an alternative method of learning the syntax of these methods, you can use
code completion by typing the name of the method and then use Ctrl+Space. A
window will open with information on the syntax and method signature.

Model Utility Methods
The model utility methods make it possible to load the model object part of an
MPH file into a method for further processing.
NAME

DESCRIPTION

clearModel

Clears the model object contents.

createModel

Creates a new model with a given tag.

removeModel

Removes a model. The embedded model cannot be removed.

modelTags

Returns an array of model tags for all loaded models, including theembedded model.

uniqueModeltag

Returns a model tag that is not in use.

getModelReturns a model with a specified tag.

loadModel

Loads a model with a specified tag from a file.

loadProtectedModel

Loads a password protected model with a specified tag from a file.

loadRecoveryModel

Loads a model from a recovery directory/folder structure.

saveModel

Saves a model to a file. The filename can be a file scheme path or,
if allowed by security settings, a server file path.

getComsolVersion

Returns the current software version as a string.

| 331File Methods
NAME

DESCRIPTION

readFile

Returns the contents in a given file as a string.

openFileStreamReader

Returns a CsReader object that can be used to readline-by-line or character-by-character from a given file
name.

openBinaryFileStreamReader

Returns a CsBinaryReader object that can be used toread from a given file byte-by-byte.

readMatrixFromFile

Reads the contents of the given file into a double matrix.
The file has the same spreadsheet-type format as available
in the model tree Export node.

readStringMatrixFromFile

Reads the contents of the given file into a string matrix.
The file has the same spreadsheet-type format as available
in the model tree Export node.

readCSVFile

Reads a file with comma-separated values (CSV file) intoa string matrix. It expects the file to use the RFC 4180
format for CSV.

writeFile

Writes array data to a given file. If the spreadsheet
format is used, then the data can be read byreadMatrixFromFile or
readStringMatrixFromFile.

openFileStreamWriter

Returns a CsWriter object that can write to a given file.

openBinaryFileStreamWriter

Returns a CsBinaryWriter object that can be used towrite to a given file byte-by-byte.

writeCSVFile

Writes a given double or string array to a CSV file. The
RFC 4180 format is used for the CSV.

existsTests whether a file with a given name exists.

deleteFile

Deletes a file with a given name if it exists. The file isdeleted on the server.

copyFile

Copies a file on the server. Both the source and target
names can use file scheme paths.

importFile

Displays a file browser dialog box and uploads theselected file to the file declaration with the given name.
Alternatively, it uploads the selected file to the Filename
text field in a given model object entity.

writeExcelFile

Writes the given string array data starting from a
specified cell in a specified sheet of an Excel file.

readExcelFile

Reads a specified sheet of an Excel file, starting from a
specified cell, into a 2D string array.

332 |

NAME

DESCRIPTION

getFilePath

Returns the absolute server file path of the server proxy
file corresponding to a certain file scheme path, or null if
the server proxy file for the given path does not exist.
This method can be used to pass the path to, forexample, a file using the temp:/// scheme to external
code or an application.

getClientFileName

Returns the original name of an uploaded file on the client
file system (or null if there is no uploaded file matching
the given file scheme path).
This method is only useful for providing user interface
feedback; for example, to get information on which
uploaded file is being used. There is no guarantee that theoriginal file would still exist on the client or even that thecurrent client would be the same as the original client.

getClientFilePath

Returns the original path of an uploaded file on the client
file system (or null if there is no uploaded file matching
the given file scheme path).
This method is only useful for providing user interface
feedback; for example, to get information on which
uploaded file is being used. There is no guarantee that theoriginal file would still exist on the client or even that thecurrent client would be the same as the original client.

| 333

Operating System Methods
NAME

DESCRIPTION

executeOSCommand

Executes the OS command with a given command (full path) andparameters. When applicable, the command is run server side.

fileOpen

Opens a file with the associated program on the client. See also
the section “File Methods”.

getUser

Returns the username of the user that is running the application. If
the application is not run from COMSOL Server, then the valueof the preference setting General>Username>Name is returned.

openURL

Opens a URL in the default browser on the client.

playSound

Plays a sounds on the client.

Email Methods
NAME

DESCRIPTION

emailFromAddress

Returns the email from address from the COMSOL Server or
preferences setting.

sendEmailSends an email to the specified recipient(s) with the specified
subject, body text, and zero or more attachments created from
Report, Export, and Table nodes in the embedded model.

userEmailAddress

Returns the user email address(es) corresponding to the currently
logged in user, or an empty string if the user has not configured anemail address.

Email Class Methods
The class EmailMessage can be used to create custom email messages.
NAME

DESCRIPTION

EmailMessage

Creates a new EmailMessage object.

EmailMessage.setServer

Sets the email (SMTP) server host and port touse for this email message.

EmailMessage.setUser

Sets the username and password to use for email(SMTP) server authentication. This method must
be called after the setServer method.

EmailMessage.setSecurity

Sets the connection security type for email(SMTP) server communication.

EmailMessage.setFrom

Sets the from address.

334 |

NAME

DESCRIPTION

EmailMessage.setTo

Sets the to addresses.

EmailMessage.setCc

Sets the cc addresses.

EmailMessage.setBcc

Sets the bcc addresses.

EmailMessage.setSubject

Sets the email subject line. Note that newline
characters are not allowed.

EmailMessage.setBodyText

Sets the email body as plain text. An email cancontain both a text and an HTML body.

EmailMessage.setBodyHtml

Sets the email body as HTML text. An email cancontain both a text and an HTML body.

EmailMessage.attachFile

Adds an attachment from a file. The attachment
MIME type is determined by the file nameextension.

EmailMessage.attachFile

Adds an attachment from a file with a specified
MIME type.

EmailMessage.attachFromModel

Adds an attachment created from a report,
export, or table feature in the model.

EmailMessage.attachText

Adds a text attachment with a specified
sub-MIME type, such as plain or HTML.

EmailMessage.attachBinary

Adds an attachment from a byte array with a
specified MIME type.

EmailMessage.send

Sends the email to the email (SMTP) server. An
email object can only be sent once.

| 335

E MAIL P REFERENCES
To set preferences for an outgoing email (SMTP) server, open the Email page of
the Preferences dialog box, as shown in the figure below.

COMSOL Server provides a similar set of email preferences.

336 |GUI-Related Methods
NAME

DESCRIPTION

Call a method directly

Call a method from the Methods list by using its name; forexample, method1(), method2().

callMethod

Alternate way to call a method from the Methods list;
used internally and in cases of name collisions.

useGraphics

Plots a given entity (Plot Group, Geometry, Mesh, orExplicit Selection) in the graphics form object given by aname or name path in the second argument.

useForm

Shows the form with a given name in the current main
window. Equivalent to the use method of a Form object;
see below.

closeDialog

Closes the form, shown as a dialog box, with a given
name.

dialogShows the form with a given name as a dialog box.
Equivalent to the dialog method of a Form object; seebelow.

alert

Stops execution and displays an alert message with agiven text.

alert

Stops execution and displays an alert message with agiven text and title.

confirm

Stops execution and displays a confirmation dialog box
with a given text and title. It also displays two or threebuttons, such as “Yes”, “No”, and “Cancel”.

error

Stops execution and opens an error dialog box with agiven message.

requestStops execution and displays a dialog box with a text field,
requesting input from the user.

message

Sends a message to the message log.

evaluateToResultsTable

Evaluates a given entity, a Derived Value, in the tableobject given by the name or name path in the second
argument, which will then be the default target for theevaluations of the Derived Value. If the third argument istrue, the table is cleared before adding the new data.
Otherwise, the data is appended.

| 337

NAME

DESCRIPTION

evaluateToDoubleArray2D

Evaluates the given entity, a Derived Value, and returns
the nonparameter column part of the real table that is
produced as a double matrix. All settings in the numericalfeature are respected but those in the current tableconnected to the numerical feature are ignored.

evaluateToIntegerArray2D

Evaluates the given entity, a Derived Value, and returns
the nonparameter column part of the real table that is
produced as an integer matrix. All settings in the
numerical feature are respected, but those in the current
table connected to the numerical feature are ignored.

evaluateToStringArray2D

Evaluates the given entity, a Derived Value, and returns
the nonparameter column part of the potentially complex
valued table that is produced as a string matrix. All
settings in the numerical feature are respected, but thosein the current table connected to the numerical feature
are ignored.

useResultsTable

Shows the values from the tableFeature in the
resultsTable form object.

getChoiceList

Returns an object of the type ChoiceList, representing
a choice list node under the declarations branch. The type
ChoiceList has associated methods that make it easy
to change values and display names, see the Application
Programming Guide.

setFormObjectEnabled

Sets the enable state for the form object specified by thename or name path.

setFormObjectVisible

Sets the visible state for the form object specified by thename or name path.

setFormObjectText

Sets the text for the form object specified by the name orname path in the second argument. This method throws
an error if it is impossible to set a text for the specified
form object.

setFormObjectEditable

Sets the editable state for the form object specified by thename or name path. This functionality is only available fortext field objects.

setMenuBarItemEnabled

Sets the enable state for the menu bar item specified by
the name or name path (from the menu bar) in the firstargument.

setMainToolbarItemEnabled

Sets the enable state for the main toolbar item specified
by the name or name path (from the main toolbar) in thefirst argument.

338 |

NAME

DESCRIPTION

setFileMenuItemEnabled

Sets the enable state for the file menu item specified by
the name or name path (from the file menu) in the firstargument.

setRibbonItemEnabled

Sets the enable state for the ribbon item specified by thename or name path (from the main window) in the firstargument.

setToolbarItemEnabled

Sets the enable state for the toolbar form object item
specified by the name or name path in the first argument.

useView

Applies a view to the graphics contents given by the nameor name path in the second argument.

resetView

Resets the view to its initial state in the graphics contents
given by the name or name path in the second argument.

getView

Returns the view currently used by the graphics contents
given by the name or name path in the second argument.

setWebPageSource

Sets the source for the form object specified by the nameor name path in the first argument.

getScreenHeight

Returns the height in pixels of the primary screen on theclient system, or of the browser window if Web Client isused.

getScreenWidth

Returns the width in pixels of the primary screen on theclient system, or of the browser window if Web Client is
used.

| 339

GUI Command Methods
NAME

DESCRIPTION

clearAllMeshes

Clears all meshes.

clearAllSolutions

Clears all solutions.

clearSelection

Clears the selection in the given graphics object.

exit

Exits the application.

fileOpen

Opens a file with the associated program on the client.

fileSaveAs

Downloads a file to the client. See also the section “File Methods”.

printGraphics

Prints the given graphics object.

saveApplication

Saves the application.

saveApplicationAs

Saves the application under a different name. (Or as an MPH file.)

scenelight

Toggles scene light in the given graphics object.

selectAll

Selects all objects in the given graphics object.

transparency

Toggles transparency in the given graphics object.

zoomExtents

Makes the entire model visible in the given graphics object.

zoomToSelection

Zooms to the current selection.

Debug Methods
NAME

DESCRIPTION

clearDebugLog

Clears the Debug Log window.

debugLog

Prints the value of an input argument to the Debug Log window.
The input argument can be a scalar, 1D array, or 2D array of thetypes string, double, integer, or Boolean.

Methods for External C Libraries
E XTERNAL M ETHODNAMEDESCRIPTION

external

Returns an interface to an external C (native) library given by thename of the library feature. The External class uses the Java
Native Interface (JNI) framework. For more information, see theApplication Programming Guide.

340 |M ETHODS R ETURNED BY THE E XTERNAL M ETHOD
The external method returns an object of type External with the following
methods:
NAME

DESCRIPTION

invokeInvokes a named native method in the library with the suppliedarguments.

invokeWideString

Invokes the named native method in the library with the suppliedarguments.

close

Releases the library and frees resources. If you do not call thismethod, it is automatically invoked when the external library is nolonger needed.

| 341

Progress Methods
NAME

DESCRIPTION

setProgressInterval

Sets a progress interval to use for the top-level progress anddisplay message at that level.
Calling this method implicitly resets any manual progress
previously set by calls to setProgress().

setProgress

Sets a value for the user-controlled progress level.

resetProgress

Removes all progress levels and resets progress to 0 and themessage to an empty string.

showIndeterminateProgressShows a progress dialog box with an indeterminate progress bar,
given message, and an optional cancel button.

showProgress

Shows a progress dialog box with an optional cancel button,
optional model progress, and one or two levels of progress
information.

closeProgress

Closes the currently shown progress dialog box.

startProgress

Resets the value of a given progress bar form object name to 0.

setProgressBar

Sets the value of a given progress bar form object name in therange 0 –100 and the associated progress message.

Date and Time Methods
NAME

DESCRIPTION

currentDate

Returns the current date as a string (formatted according to theserver's defaults) for the current date.

currentTime

Returns the current time as a string (not including date and formatted
according to the server's defaults).

formattedTime

Returns a formatted time using the given format. The format caneither be a time unit or text describing a longer format.

sleep

Sleep for a specified number of milliseconds.

timeStamp

Current time in milliseconds since midnight, January 1, 1970 UTC.

getExpectedComp
utationTime

Returns a string describing the approximate computation time of theapplication. The string can be altered by the method
setExpectedComputationTime.

342 |

NAME

DESCRIPTION

setLastComputat
ionTimeSet the last computation time, overwriting the automaticallygenerated time.
You can use the timeStamp method to record time differences andthen set the measured time in ms (a long integer).

getLastComputat
ionTimeReturns the last computation time in the given format. The format caneither be a time unit or text describing a longer format. This format is
localized and the output is translated to the current language setting.

| 343

License Methods
NAME

DESCRIPTION

checkoutLicense

Checks out one license for each specified product.

checkoutLicenseForFile

Checks out one license for each product required to open an
MPH file.

checkoutLicenseForFil
eOnServer

Checks out one license for each product required to open an
MPH file.

getLicenseNumber

Returns a string with the license number for the current
session. Example: licensenumber=getLicenseNumber()

hasProduct

Returns true if the COMSOL installation contains thesoftware components required for running the specified
products.

hasProductForFile

Returns true if the COMSOL installation contains thesoftware components required for running the specified MPH
file.

hasProductForFileOnSe
rver

Returns true if the COMSOL installation contains thesoftware components required for running the specified MPH
file.

Conversion Methods
NAME

DESCRIPTION

toBoolean

Converts strings and string arrays to Booleans. (‘true’ returns true, allother strings return false).

toDouble

Converts floats, float arrays, strings, and string arrays to doubles.

toInt

Converts strings and string arrays to integers.

toString

Converts Booleans, integers, and doubles, including arrays, to strings.

Array Methods
NAME

DESCRIPTION

getColumn

Returns a string, double, integer, or Boolean array for a specified column
in a 2D array (matrix). This is, for example, useful when values have beenread from a file and only certain columns should be shown in a table.

getSubMatrix

Returns a rectangular submatrix of an input matrix. Available for string,double, integer, or Boolean 2D arrays.

insertInserts one or more elements in an array and returns the expanded array.
Available for string, double, integer, or Boolean arrays.

344 |

NAME

DESCRIPTION

appendAdds one or more elements to the end of an array and returns the
expanded array. Available for string, double, integer, or Boolean arrays.

removeRemoves one or more elements from an array and returns the shortenedarray. Available for string, double, integer, or Boolean arrays.

insertRow

Inserts one or more rows into a rectangular 2D array and returns the
expanded array. Available for string, double, integer, or Boolean arrays.

appendRow

Adds one or more rows to the end of a rectangular 2D array and returns
the expanded array. Available for string, double, integer, or Boolean arrays.

removeRow

Removes one or more rows from a 2D array and returns the reduced
array. Available for string, double, integer, or Boolean arrays.

replaceRow

Replaces one or more rows in a rectangular 2D array and returns thearray. Available for string, double, integer, or Boolean arrays.

insertColumn

Adds one or more columns into a rectangular 2D array and returns the
expanded array. Available for string, double, integer, or Boolean arrays.

appendColumn

Adds one or more columns at the end of a rectangular 2D array andreturns the expanded array. Available for string, double, integer, or
Boolean arrays.

removeColumn

Removes one or more columns from a rectangular 2D array and returns
the smaller array. Available for string, double, integer, or Boolean arrays.

replaceColumn

Replaces one or more columns in a rectangular 2D array and returns thearray. Available for string, double, integer, or Boolean arrays.

matrixSize

Returns the number of rows and columns of a matrix as an integer arrayof length 2. Available for string, double, integer, or Boolean arrays.

| 345

String Methods
NAME

DESCRIPTION

concatConcatenates a given array or matrix of strings into a single string using
the given separators.

contains

Returns true if a given string array contains a given string.

find

Returns an array with the indices to all occurrences of a string in a stringarray.

findInReturns the index to the first occurrence of a string in a string array or the
first occurrence of a substring in a string.

lengthReturns the length of a string.

replace

Returns a string where a string has been replaced with another string.

split

Returns an array of strings by splitting the given string at a given separator.

substring

Returns a substring with the given length starting at the given position.

uniqueReturns an array of strings with the unique values in the given array ofstrings.

Collection Methods
NAME

DESCRIPTION

copy

Returns a copy of the given array or matrix. Available for string, double,
integer, or Boolean arrays.

equalsReturns true if all elements in the given array are equal and they have thesame number of elements. Available for string, double, integer, or Boolean
arrays. For doubles, comparisons are made using a relative tolerance.

sort

Sorts the given array. Note: The array is sorted in place. Available forstring, double, or integer arrays. If the array is two-dimensional (a matrix),
the columns are sorted by their row values from top to bottom.

merge

Returns an array with all of the elements merged from the given arrays.
Available for string, double, or integer arrays.

With, Get, and Set Methods
NAME

DESCRIPTION

with

Used to make code more compact.

endwithThe ending of a with statement.

set

Sets a Boolean, integer, double, or string property value. Allows
for a scalar, array, or matrix property.

346 |

NAME

DESCRIPTION

setIndex

Sets a string, double, or integer property value for a matrix orvector at a given index.

getIntArray

Gets an integer vector property.

getIntMatrix

Gets an integer matrix property.

getBoolean

Gets a Boolean property.

getBooleanArray

Gets a Boolean vector property.

getBooleanMatrix

Gets a Boolean matrix property.

getDouble

Gets a double property.

getStringGets a string scalar, vector, or matrix property.

getDoubleArray

Gets a double vector property or parameter.

getDoubleMatrix

Gets a double matrix property or parameter.

getStringArray

Gets a string vector property or parameter.

getStringMatrix

Gets a string matrix property or parameter.

getDblStringArray

Returns the value as a matrix of strings.

getIntGets an integer property.

getReturns a variable expression.

descr

Returns a variable description.

Model Builder Methods for use in Add-Ins
For writing add-in method code that operates on the current component, current
mesh, current physics etc. use the methods in the table below.
NAME

DESCRIPTION

getCurrentComponent

Returns an object of the type ModelNode for the current
component.

getCurrentPhysics

Returns an object of the type Physics for the current physics
interface.

getCurrentMesh

Returns an object of the type MeshSequence for the current
mesh.

getCurrentStudy

Returns an object of the type Study for the current
component.

getCurrentPlotGroup

Returns an object of the type ResultFeature for the current
component.

| 347

NAME

DESCRIPTION

getCurrentNode

Returns an object of the type ModelEntity for the current
component.

selectNode

Select a particular model tree node.

These methods return the corresponding entity such that the method code in an
add-in can operate on it. When called from an application a method in thiscategory returns null. Also, null is returned if no entity of the corresponding
type exists such that nothing is current.

348 |Appendix F — Guidelines for Building Applications
General Tips
• Include reports to files with input data and corresponding output data.
• Make it intuitive. Provide help, hints, and documentation as necessary.
• Make it foolproof: “Safe I/O”, “Reset to default data”, etc.
• Save a thumbnail image with the model.
• Include a description text (It will be visible in the COMSOL Server library).
• Test the application on the computer platforms for which it is intended.
• Be minimalistic. From the developer’s point of view, it is much easier tomake sure logic works, organize, debug, maintain, and further develop theapp. From a user’s point of view, it is easier to use the application. The
minimalistic approach requires more care while developing but much lessmaintenance later on and much higher adoption among users.
• Embed libraries in the model if they are of manageable size.
• Display the expected computation time and, after the computation, theactual computation time.
• When a computation is canceled, output data from the previous

computation should be cleared.
• Password protect as needed. (Remember: No one can help you if you forgetthe password.)

Naming Conventions
In the demo applications in the Application Libraries, all forms, events,
declarations and methods use camelCase. You can adopt this convention also in
your own applications. Following this convention, a name should be composed ofa number of words joined without spaces, with each word's initial letter in capitals
except the first letter that should be lowercase. Use a descriptive name and long
names are better than hard-to-understand short names.
Examples of names for forms:• main• inputParameters• geometryTab| 349

Examples of names for events:• updatePlot• moveToVelocityTab

Examples of names for declarations:• Strings — state, waveguideType• Boolean — isError, didChange, hasBeenInitialized• Integer — year, nextYear• Double — speed, heatTransferCoefficient

Examples of names for methods:• compute();• computeStudy1();• computeStudyAndPlot();• getDataForPostProcessing();• setPlotType();

Methods• Do not create more methods than necessary.

Fewer methods give you a shorter list of methods to browse through whenlooking for something. Fewer methods usually mean fewer lines of code toworry about.
- If several methods you wrote do essentially the same thing, consider merging

them into one method and dealing with the different cases by input
arguments.
- Do not create a method if it is only called from one place. Insert the coderight into that place instead.
• Create a local method if it is only used in a form, or triggered by a form

event or a form object event.
• Give methods descriptive names and name them so that similar methods aregrouped together when sorted alphabetically. You will have less toremember and you will find what you are looking for easier. Long names are
better than hard-to-understand short names.
• The points above apply to method code as well: be minimalistic, use as few

lines of code and variables as possible, use descriptive names for variables,
use long names instead of hard-to-understand short names, and optimize
code to run efficiently.

350 |• The above points apply to declarations as well: use good names, don't use

more than necessary, and declare variables where they are used (in forms andmethods or in the model).

Forms• Do not create more forms than necessary.
• Give forms descriptive names. Same reasoning as for methods.
• Make good use of the many different types of form objects. Some are goodfor some things, while some are good for others.
• Do not insert more form objects than necessary. Too many options for input

data may make the application hard to use. Too much output data makes it
hard to find important information.
• Insert a text field for the user to leave comments to save with the user’s setof input and output data when saving the application.
• Consider inserting a button with a method to reset to default data.
• Apply “Safe I/O”:- For input fields, alert the user about input data that is out of bounds. You cando that either by an alert triggered by an On Data Change event for an input
field, or by setting limits in the form objects settings window, which then sets
hard limits. In a method generating the alert, you may just warn the user andthen allow the input data if the user chooses to go ahead anyway.
- On output fields, give the precision that makes sense. If current results are

not based on current input data, show it. If the computation failed, show it.
• Include tooltips, help, documentation, hints, and comprehensive reports.
• Provide the user with information about how long it takes to run thesimulation with default input data on a typical computer. It could beseconds, hours, or even days depending on the application, so that issomething the user would like to know before hitting the compute button.
Consider playing a sound to alert the user when the computation has
finished. The user may be doing something else while waiting for results.
(Sending an email message with a report to the user or some other placewhen the computation is done may be a better alternative if the computationis really long.)• Spend some time on the layout of a form. A good-looking form makes it

easier and more fun to use the application.
Consider setting keyboard shortcuts for buttons and menu items.

| 351

Appendix G — The Application Library Examples
In the Application Libraries, you can find example applications that showcase thecapabilities of the Application Builder. They are collected in folders with the nameApplications and are available for many of the add-on products. You can edit theseapplications and use them as a starting point or inspiration for your own
application designs. Each application contains documentation (PDF) describing
the application and an option for generating a report.
Below is a partial list of the available application examples organized as they appear
in the Application Libraries tree. Note that some applications may require
additional products to run.
NAME

APPLICATION LIBRARY

Cluster Setup Validation

COMSOL Multiphysics

Helical Static Mixer

COMSOL Multiphysics

Transmission Line Calculator

COMSOL Multiphysics

Tubular Reactor

COMSOL Multiphysics

Tuning ForkCOMSOL Multiphysics

B-H Curve Checker

AC/DC Module

Effective Nonlinear Magnetic Curves

AC/DC Module

Induction Heating of a Billet

AC/DC Module

Organ Pipe Design

Acoustics Module, Pipe Flow Module

Lithium Battery Designer

Battery Design Module

Lithium Battery Pack Designer

Battery Design Module

Lithium-Ion Battery ImpedanceBattery Design Module

Water Treatment Basin

CFD Module

Reaction Equilibrium - Gas Phase Conversion of
Ethylene to Ethanol

Chemical Reaction Engineering Module

Cyclic Voltammetry

Electrochemistry Module

Electrochemical Impedance Spectroscopy

Electrochemistry Module

Concentric Tube Heat Exchanger

Heat Transfer Module

Equivalent Properties of Periodic Microstructures

Heat Transfer Module

Finned Pipe

Heat Transfer Module

Forced Air Cooling with Heat Sink

Heat Transfer Module

Inline Induction Heater

Heat Transfer Module

352 |

NAME

APPLICATION LIBRARY

Thermoelectric Cooler

Heat Transfer Module

Mixer

Mixer Module

Charge Exchange Cell Simulator

Molecular Flow Module, Particle Tracing
ModuleTruck Mounted Crane Analyzer

Multibody Dynamics Module

General Parameter Estimation

Optimization Module

Heat Recovery for System for Geothermal Heat
Pump

Pipe Flow Module

Solar Dish Receiver Designer

Ray Optics Module

Corrugated Circular Horn Antenna

RF Module

Frequency Selective Surface Simulator

RF Module

Slot-Coupled Microstrip Patch Antenna Array
Synthesizer

RF Module

Rotor Bearing System Simulator

Rotordynamics Module

Si Solar Cell with Ray Optics

Semiconductor Module

Beam Section Calculator (Using LiveLink™ for
Excel)Structural Mechanics Module, LiveLink™
for Excel

Beam Section Calculator

Structural Mechanics Module

Bike Frame Analyzer

Structural Mechanics Module, LiveLink™
for SOLIDWORKS

Fiber Simulator

Wave Optics Module

Plasmonic Wire Grating Analyzer

Wave Optics Module

Polarizing Beam Splitter

Wave Optics Module

The following sections highlight some of the applications listed in the table above.
The highlighted applications exemplify a variety of important Application Builder
features, including the use of animations, email, optimization, parameter
estimation, tables, and the import of experimental data.

Helical Static Mixer
This app demonstrates the following:• Geometry parts and parameterized geometries• Dark theme• Material appearance visualization with environment reflections• Report generation for both Microsoft® Word and Microsoft® PowerPoint| 353

• Options for setting different mesh sizes• Improved graphics visualization when showing and hiding different

geometry objects• Enabling and disabling ribbon items based on the solution state.

Helical static mixers are often used to mix monomers and initiators which thenreact during a polymerization process. The concentration field is included in theanalysis in order to compute the extent of mixing between two streams injected
into the static mixer through semicircle-shaped inlets.
The app can be used to estimate the degree of mixing in a system including one
to five helical blades whose dimensions can also be varied. The monomers' liquid
properties and inlet velocity can also be varied.
This application does not require any add-on products.

Transmission Line Calculator
This app demonstrates the following:• Creating apps for small screens such as smartphones• User-interface navigation with a top menu typically used on websites• Dynamically hiding forms using card stacks to minimize the space requiredby the app• Changing appearance by using different background colors.

354 |Transmission line theory is a cornerstone in the teaching of RF and microwave
engineering. Transmission lines are used to guide waves of electromagnetic fields
at radio frequencies. They exist in a variety of forms, many of which are adapted
for easy fabrication and employment in printed circuit board (PCB) designs.
Often, they are used to carry information, with minimal loss and distortion, withina device and between devices.
Electromagnetic fields propagate along transmission lines as transverse
electromagnetic (TEM) waves. The Transmission Line Parameter Calculator app
computes resistance (R), inductance (L), conductance (G), and capacitance (C) as
well as the characteristic impedance and propagation constant for some common
transmission lines types: coaxial line, twin lead, microstrip line, and coplanar
waveguide (CPW).
This application does not require any add-on products.

| 355

Tubular Reactor
This app demonstrates the following:• Sending an email with a report when the computation is finished• User-defined email server settings• Playing a sound when the computation is completed• Options to visualize plots tiled or tabbed.

The app exemplifies how students in chemical engineering can model nonideal
tubular reactors (radial and axial variations) and investigate the impact of different
operating conditions. It is also a great example of how teachers can build tailoredinterfaces for problems that challenge the students’ imaginations.
The model describes a tubular reactor where propylene oxide (A) reacts with water(B) to form propylene glycol (C):A + B -> C
Since water is the solvent and present in abundance, the reaction kinetics may bedescribed as first order with respect to propylene oxide
R = k*C_A
Alternatively, a second-order reaction can also be implemented according to
R = kf*C_A*C_B - kr*C_C
The reaction is exothermic and a cooling jacket is used to cool the reactor. The
reactor is modeled in 2D axisymmetry and the simulation results yieldcomposition and temperature variations in both the radial and axial directions.

356 |This application does not require any add-on products.

Tuning ForkThis app demonstrates the following:• Playing a sound at a specific computed frequency• Selecting different materials from a combo box• Visualizing material appearance, color, and texture• Choice of three different user interface layouts for computer, tablet, or

smartphone• Custom implementation of the secant method• Custom window icon.

When a tuning fork is struck, it vibrates in a complex motion pattern that can be
described mathematically as the superposition of resonant modes, also known aseigenmodes. Each mode is associated with a particular eigenfrequency. The tuning
fork produces its characteristic sound from the specific timbre that is created by
the combination of all of the eigenfrequencies.
The app computes the fundamental resonant frequency of a tuning fork where you
can change the prong length. Alternatively, you can provide a user-defined target
frequency and the application will find the corresponding prong length using analgorithm based on a secant method.

| 357

This application does not require any add-on products.

B-H Curve Checker
This app demonstrates the following:• Importing measured data from a text file• Handling measured data using methods• Exporting the results to a text file.

The app can be used to verify and optimize B-H curves using experimental data.
It also generates curve data in the over-fluxed region, where measurement are
difficult to perform. It removes the unphysical ripples of the slope of the B-H
curve that might cause numerical instability.
The original B-H curve is evaluated from two aspects. Firstly, to verify that theextrapolation of the curve is reasonable from the physical point of view. Secondly,
to check if the slope of the curve is smooth. The optimization algorithms aremainly based on the simultaneous exponential extrapolation method and thelinear interpolation method, respectively.
The app requires the original curve data defined in a text input file. Once the curveis imported, the application checks if optimization is required. By clicking the
Optimize Curve button, the user can generate the optimized curve data, which canbe exported to a text file.

358 |This application does not require any add-on products.

Induction Heating of a Steel Billet
This app demonstrates the following:• Geometry parts and parameterized geometries• Using tables for user input parameters• Visualization on a 2D cross-section of a 3D geometry• Improved visualization and user experience when a geometry object (the air

object) is hidden.
Induction heating is a method used to heat metals for forging and otherapplications. Compared with more traditional heating methods, such as gas orelectric furnaces, induction heating delivers heating power directly to the piece ina more controlled way and allows for a faster processing time.
The app is used to design a simple induction heating system for a steel billet,
consisting of one or more electromagnetic coils through which the billet is moved
at a constant velocity. The coils are energized with alternating currents and induce
eddy currents in the metallic billet, generating heat due to Joule heating. The
billet cross section; the coil number, placement, and size; as well as the initial andambient temperature and the individual coil currents can all be specified as inputs
in the app.

| 359

This application requires the AC/DC Module.

Effective Nonlinear Magnetic Curves Calculator
This app demonstrates the following:• Importing measured data from a text file• Handling measured data using methods• Exporting the results to a text file• Exporting the results as COMSOL Material Library file.

The app is a companion to the Effective Nonlinear Constitutive Relations
functionality. Magnetic-based interfaces in the AC/DC Module support the
Effective HB/BH Curve material model that can be used to approximate thebehavior of a nonlinear magnetic material in a frequency domain simulation
without the additional computational cost of a full transient simulation.
The Effective HB/BH Curve material model requires the effective Heff(B) or
Beff(H) relations defined as interpolation functions. This utility app can be used
to compute the interpolation data starting from the material’s H(B) or B(H)relations.
The interpolation data for the H(B) or B(H) relations can be imported from a text
file or entered in a table. The app then computes the interpolation data for the
Heff(B) or Beff(H) relations using two different energy methods. The resulting

360 |effective material properties can be exported as a COMSOL Material Library fileand be further used in a model with the Magnetic Fields interface.
This application does not require any add-on products.

Organ Pipe Design
This app demonstrates the following:• Using a Java® utility class for combining several waveforms and for playing

sound• Using tables for presenting results.

The app allows you to study the design of an organ pipe and then play the soundand pitch of the changed design. The pipe sound includes the effects of different
harmonics with different amplitudes.
The organ pipe is modeled using the Pipe Acoustics, Frequency Domain interface.
The app allows you to analyze how the first fundamental resonance frequency
varies with the pipe radius and wall thickness, as well as with the ambient pressure
and temperature.
Using the app, you can find the full frequency response, including thefundamental frequency and the harmonics. With a method written in Java®code,
the app detects the location and amplitude of all harmonics in the response, thus
extending the analysis beyond the built-in functionality of the COMSOLMultiphysics user interface.

| 361

This application requires the Acoustics Module.

Lithium Battery Designer
This app can be used as a design tool to develop an optimized battery
configuration for a specific application. The application computes the capacity,
energy efficiency, heat generation, and capacity losses due to parasitic reactions ofa battery for a specific load cycle.
Various battery-design parameters consist of: geometrical dimensions of thebattery canister, the thicknesses of the different components (separator, current
collectors and electrodes), the positive electrode material, and the volume
fractions of the different phases of the porous materials can be changed. The load
cycle is a charge-discharge cycle using a constant current load, which may bedifferent for the charge and discharge stages.

362 |The app also computes the battery temperature (assuming an uniform internal
battery temperature), based on the generated heat and the thermal mass. Coolingis defined using an ambient temperature parameter and a heat transfer coefficient.

Li-Ion Battery Pack Designer
This app demonstrates the following:• Dynamic help system using card stacks• Multiple components (1D and 3D) in a single app• Toggle buttons in the ribbon for showing different input, hiding/showing

geometry selections, and for dynamic help
• Geometry parts and parameterized geometries• Importing experimental data
• Options for creating different mesh sizes• Resetting a portion of the input parameters or all• Generating a results table during the app session• Exporting results to a text file or to Microsoft ® Excel if a license of

LiveLink™ for Excel® is available• Sliders and buttons to control the time step to plot

| 363

• Visualizing results with animations• Custom window icons.

It is a tool for investigating the dynamic voltage and thermal behavior of a battery
pack, using load cycle and SOC vs OCV dependence experimental data.
Parameter estimation of various parameters such as the ohmic overpotential, thediffusion time constant, and the dimensionless exchange current can be performedby the app. The app may then be used to compute a battery pack temperature
profile based on the thermal mass and generated heat associated with the voltage
losses of the battery.
Various battery pack design parameters (packing type, number of batteries,
configuration, geometry), battery material properties, and operating conditions
can be varied.
This application requires the Battery Design Module and the Optimization
Module.

Li-Ion Battery Impedance
The goal with this app is to explain experimental electrochemical impedance
spectroscopy (EIS) measurements and to show how you can use a simulation app,
along with measurements, to estimate the properties of lithium-ion batteries.

364 |The app takes measurements from an EIS experiment and uses them as inputs. It
then simulates these measurements and runs a parameter estimation based on theexperimental data.
The control parameters are: the exchange current density, the resistivity of thesolid electrolyte interface on the particles, the double-layer capacitance of NCA,
the double-layer capacitance of the carbon support in the positive electrode, andthe diffusivity of the lithium ion in the positive electrode. Fitting is done to themeasured impedance of the positive electrode at frequencies ranging from 10mHz to 1 kHz.
The application requires the Optimization Module and the Battery Design
Module.

| 365

Water Treatment Basin
This app demonstrates the following:• Parameterized geometry containing a geometry sequence with if-statements

to produce different types of designs• Options to set the mesh size
• Light Theme• A graphical user interface that includes different windows that can be shownor hidden.
Water treatment basins are used in industrial-scale processes in order to remove
bacteria or other contaminants.
The app exemplifies modeling turbulent flow and material balances subject tochemical reactions. You can specify the dimensions and orientation of the basin,
mixing baffles, and inlet and outlet channels. You can also set the inlet velocity,
species concentration, and reaction rate constant in the first-order reaction.
The app solves for the turbulent flow through the basin and presents the resulting
flow and concentration fields as well as the space-time, half-life, and pressure drop.
The application requires the CFD Module.

366 |Reaction Equilibrium—Gas Phase Conversion of Ethylene to EthanolThis app demonstrates the following:• How an app can be used as a teaching tool
• An 8 question multiple choice quiz where the answers can be sent to thegrader by email
This app calculates the equilibrium compositions in gas phase conversion of
ethylene to ethanol. It allows you to study how the initial conditions and theoperating conditions affect the ethanol production.
The app is designed to teach you how to compute quantitative results for theequilibrium composition and provide an understanding for the dynamics of achemical equilibrium.
The application requires the Chemical Reaction Engineering Module.

Cyclic Voltammetry
The purpose of the app is to demonstrate and simulate the use of cyclic
voltammetry. You can vary the bulk concentration of both species, transport
properties, kinetic parameters, as well as the cycling voltage window and scan rate.
Cyclic voltammetry is a common analytical technique for investigating
electrochemical systems. In this method, the potential difference between aworking electrode and a reference electrode is swept linearly in time from a start| 367

potential to a vertex potential, and back again. The current-voltage waveform,
called a voltammogram, provides information about the reactivity and masstransport properties of an electrolyte.
The application requires one of the Battery Design Module, Electrochemistry
Module, Electrodeposition Module, Corrosion Module, or Fuel Cell &Electrolyzer Module.

Electrochemical Impedance Spectroscopy
The purpose of this app is to understand EIS, Nyquist, and Bode plots. The app
lets you vary the bulk concentration, diffusion coefficient, exchange current
density, double layer capacitance, and the maximum and minimum frequency.
Electrochemical impedance spectroscopy (EIS) is a common technique inelectroanalysis used to study the harmonic response of an electrochemical system.
A small, sinusoidal variation is applied to the potential at the working electrode,and the resulting current is analyzed in the frequency domain.
The real and imaginary components of the impedance give information about the
kinetic and mass transport properties of the cell, as well as the surface properties
through the double layer capacitance.

368 |The application requires one of the Battery Design Module, Electrochemistry
Module, Electrodeposition Module, Corrosion Module, or Fuel Cell &Electrolyzer Module.

| 369

Concentric Tube Heat Exchanger
This app demonstrates the following:• Selecting predefined or user-defined materials• User option to switch between laminar flow or turbulent flow
• Changing boundary conditions using methods• Visualizing temperature dependent material properties as graph plots• User option to set the solver tolerance.

Finding the right dimensions for a heat exchanger is imperative to ensure its
effectiveness. Other properties must also be considered in order to design a heatexchanger that is both of the right size and provides heated or cooled fluid of theright temperature.
The app computes these quantities for a heat exchanger made of two concentric
tubes. The fluids can flow either in parallel or in counter current flow.
The fluid properties, heat transfer characteristics, and dimensions of the heatexchanger can all be varied. The Nonisothermal Flow multiphysics interface isused to model the heat transfer.
This application requires the Heat Transfer Module.

370 |Equivalent Properties of Periodic Microstructures
This app demonstrates the following:• Visualization of a periodic structure from a unit cell
• Resetting some or all input parameters• Export the resulting material properties as an MPH-file or an XML-file thatcan be imported to a COMSOL Multiphysics session.
Periodic microstructures are frequently found in composite materials, such ascarbon fibers and honeycomb structures. They can be represented by a unit cell
repeated along three directions of propagation.
To reduce computational costs, simulations may replace all of the microscopic
details of a composite material with a homogeneous domain with equivalent
properties. This app computes the equivalent properties for a geometricalconfiguration and the material properties of a unit cell to be used in a macroscopic
model that uses these composite materials.
Nine different microstructures are given, with dimensional characteristics that aremodifiable by the user, as well as thirteen predefined materials. The app calculates
the equivalent density, heat capacity, and thermal conductivity or diffusivity of thecomposite materials.
This application does not require any add-on products.

| 371

Finned Pipe
This app demonstrates the following:• Geometry parts and parameterized geometry• A results table form object containing outputs.

Finned pipes are used for coolers, heaters, or heat exchangers to increase heattransfer. They come in different sizes and designs depending on the application
and requirements.
When the fins are placed outside the pipe, they increase the heat exchange surfaceof the pipe so that a cooling or heating external fluid can exchange heat more
efficiently. When placed inside the pipe, it is the inner fluid that benefits from anincreased heat exchange surface. Instead of fins, grooves can also increase the heatexchange surface, particularly inside the pipe where space is limited.
With this app, you can customize a long cylindrical pipe with predefined inner andouter fins or grooves to observe and evaluate their cooling effects. The app
calculates the thermal performance of a pipe that is filled with water and thencooled or heated by surrounding air with forced convection.
Various geometric configurations are available for the outer structure(disk-stacked blades, circular grooves, helical blades, helical grooves, or none) andfor the inner structure (straight grooves or none).
The app computes the dissipated power and the pressure drop as functions of thegeometry and air velocity.

372 |This application requires the Heat Transfer Module

Forced Air Cooling with Heat Sink
This app demonstrates the following:• Geometry parts and parameterized geometries• Sending an email with a report when the computation is finished• User-defined email server settings which is useful when running compiled

standalone applications• Options for setting different mesh sizes• Error control of input parameters using methods.

Heat sinks are usually benchmarked with respect to their ability to dissipate heat
for a given fan curve. One possible way to carry out this type of experiment is toplace the heat sink in a rectangular channel with insulated walls.
The temperature and pressure at the channel’s inlet and outlet, as well as thepower required to keep the heat sink base at a given temperature, is thenmeasured. Under these conditions, it is possible to estimate the amount of heatdissipated by the heat sink and the pressure loss over the channel.
The purpose of the app is to carry out investigations of such benchmarking
experiments. You can vary the type of heat sink as well as the number of fins or| 373

pins and their dimensions to find the optimal design for a given pressure loss overthe channel.
Air velocities and heat source rates can be varied and the app solves fornonisothermal flow, assuming turbulence as described by the algebraic yPlus
model.
This application requires the Heat Transfer Module.

Inline Induction HeaterThis app demonstrates the following:• A model using symmetry while the results are visualized in full 3D• Provides info if the results are above or below certain critical values• Selecting predefined or user-defined materials• Error control of geometry parameters using methods and presentation of

possible errors using card stacks• Sliders and buttons to control the position of the slice when visualizing theresults with a slice plot.
The app computes the efficiency of a magnetic induction apparatus for the heatingof liquid food flowing in a set of ferritic stainless steel pipes.

374 |Ferritic stainless steels become more and more used in food processing due to theirrelatively low and stable price, and their magnetic properties that allow using newheating techniques.
A circular electromagnetic coil is wound around a set of pipes in which a fluid
flows. The alternating current passing through the coil generates an alternating
magnetic field that penetrates the pipes, generates eddy currents inside them, andheats them up. Then heat is transferred to the fluid essentially by conduction.
Various configurations are available for the set of pipes (number, length, thickness,material) and for the coil (number of turns, wire radius, current density, andexcitation frequency) to optimize the heat exchange with the fluid, while ensuringhomogeneous temperatures within it for a given flow rate.
This application requires the Heat Transfer Module and the AC/DC Module.

Thermoelectric Cooler
This app demonstrates the following:• Visualizing material appearance, color, and texture• Showing info below the graphics about geometry parameters, results andperformance depending on the selected plot action
Thermoelectric coolers are widely used for electronics cooling in various
application areas, ranging from consumer products to spacecraft design. A| 375

thermoelectric module is a common type of component used in thermoelectricity
applications. A typical module consists of several thermoelectric legs sandwiched
between two thermally conductive plates, one cold and one hot. The device thatneeds to be cooled down must be attached to the cold face.
Due to the variety of applications, there can be many different thermoelectriccooler configurations. This app covers the basic design of a single-stage
thermoelectric cooler of different sizes with different thermocouple sizes anddistributions. It also serves as a starting point for more detailed calculations withadditional input options and can be extended to multistage thermoelectriccoolers.
This application requires the Heat Transfer Module, AC/DC Module, andOptimization Module. Instead of the AC/DC Module you could alternatively use
the MEMS Module or the Plasma Module.

376 |MixerThis app demonstrates the following:• Multiple tabs in the ribbon• Geometry parts and parameterized geometries• Parts and cumulative selections can be used to automatically set domain andboundary settings in the embedded model• Adding or removing geometry parts with different geometricalconfiguration• Options for creating different mesh sizes• Sending an email with a report when the computation is finished• User-defined email server settings which is useful when running compiled

standalone applications• Sliders to control the visualization of a slice plot.

The app provides a user-friendly interface where scientists and process engineers
can investigate the influence that vessels, impellers, baffles, and operating
conditions have on the mixing efficiency and on the power that is required to drive
the impellers. You can use this application to understand and optimize the designand operation of a mixer for a given fluid.
You can specify the dimensions of the vessel from a list of three types and thedimensions and configuration of the impellers from a list of eleven types. The
vessels can also be equipped with baffles. You can further specify the impeller
speed and the properties of the fluid that is being mixed.

| 377

The application requires either the CFD Module or the Polymer Flow Module.

Charge Exchange Cell Simulator
A charge exchange cell consists of a region of gas at an elevated pressure within avacuum chamber. When an ion beam interacts with the higher-density gas, theions undergo charge exchange reactions with the gas which then create energetic
neutral particles. It is likely that only a fraction of the beam ions will undergocharge exchange reactions. Therefore, in order to neutralize the beam, a pair ofcharged deflecting plates are positioned outside the cell. In this way, an energetic
neutral source can be produced.
This app simulates the interaction of a proton beam with a charge exchange cell
containing neutral argon. User input includes several geometric parameters for thegas cell and vacuum chamber, beam properties, and the properties of the charged
plates that are used to deflect the remaining ions.
The simulation app computes the efficiency of the charge exchange cell, measured
as the fraction of ions that are neutralized, and records statistics about the different
types of collisions that occur.

378 |This application requires the Particle Tracing Module and the Molecular Flow
Module.

Truck Mounted Crane Analyzer
This app demonstrates the following:• Using the knob form object• Updating the geometry by rotating a knob
• Provides info if the results are above or below certain critical values

Many trucks are equipped with cranes for handling loads and such cranes have anumber of hydraulic cylinders that control the motion of the crane. Thesecylinders and other components that make up the crane are subjected to large
forces when handling heavy loads. In order to determine the load-carrying
capacity of the crane, these forces must be computed.
In the app, a rigid-body analysis of a crane is performed in order to find the
payload capacity for the specified orientation and extension of the crane.
Inputs include the angle between the booms, the total extension length, thecapacity of the inner and outer boom cylinders, and the capacity extension
cylinders. Results from the app include the payload capacity and hydraulic cylinderusage.

| 379

The application requires the Multibody Dynamics Module.

General Parameter Estimation
This app demonstrates the following:• Importing measured data from a text file or use built-in functionality fordata generation• Automatically change solver options based on the input• Dynamically update the equation display.

The app can be used to estimate parameters in models without any physics. Data
can be imported from a file or the built-in functionality for data generation can beutilized.
The models include linear, quadratic, sigmoid, sloped Gaussian, and a custom
model with up to 5 parameters.
The Levenberg–Marquardt solver computes confidence intervals for the estimatedparameters, while the other solvers (MMA, SNOPT, and BOBYQA) allow for
specification of parameter bounds. MMA and BOBYQA allow for minimizationof the maximum square instead of the sum.

380 |The application requires the Optimization Module.

Geothermal Heat Pump
This app demonstrates the following:• Changing the design by using a combo box with predefined options• Options for creating different mesh sizes• Editing and plotting monthly data input• Setting the end time and the time steps size of a time dependent simulation• Visualizing the initial values for a time dependent simulation• Includes a simple control system to manage the temperature.

Geothermal heating is an environmentally friendly and energy-efficient method to
supply modern and well insulated houses with heat. Heat exchangers placed at a
sufficient depth in the ground below the house utilize subsurface heat, where
temperatures are almost constant throughout the year.
The app studies different pipe configurations of a ground heat exchanger. It
provides information on the performance of ground-coupled heat exchangers fordifferent specifications (depth, pattern, pipes configuration, and heating
conditions), temperature conditions, soil thermal conductivity, and temperature
gradient.

| 381

The heater can also be turned off if the daily heat demand is achieved, and thenturned on again after 24 hours. The temperature at the pipe’s outlet can becontrolled and compared to the minimum temperature required in the heatexchanger specifications.
This application requires the Pipe Flow Module.

Solar Dish Receiver Designer
Solar concentrator/cavity receiver systems can be used to focus incident solar
radiation into a small region, generating intense heat which can then be converted
to electrical or chemical energy. A common figure of merit in solar thermal powersystems is the concentration ratio, or the ratio of the solar flux on the surface ofthe receiver or in the focal plane to the ambient solar flux.
This app is an application based on the Solar Dish Receiver tutorial model. In thisapp, incident solar radiation is reflected by a parabolic dish, while the concentrated
solar radiation is collected in a small cavity. A total of six different parameterized
cavity geometries are available for investigation: Cylindrical, Dome,Heteroconical, Elliptical, Spherical, and Conical. It is also possible to take several
different types of perturbation into account, including solar limb darkening andsurface roughness. For each cavity geometry, built-in plots show the flux
distribution and concentration ratio in the focal plane as well as the incident flux
on the interior surfaces of the cavity.

382 |You can learn more about this example in a related blog post: “Efficiently
Optimizing Solar Dish Receiver Designs”:
https://www.comsol.com/blogs/efficiently-optimizing-solar-dish-receiver-designs/.

This application requires the Ray Optics Module.

Corrugated Circular Horn AntennaThis app demonstrates the following:• A toolbar with large buttons for the navigation instead of a ribbon• Subforms used as sections and the sections' headings include an image• Provides info if the results are within a certain range• Visualizes a 2D axisymmetric model in full 3DThe excited TE mode from a circular waveguide passes along the corrugated innersurface of a circular horn antenna where a TM mode is also generated. When
combined, these two modes give lower cross-polarization at the antenna aperture.
By using this app, the antenna radiation characteristics, as well as aperturecross-polarization ratio can be improved by modifying the geometry of theantenna.

| 383

This application requires the RF Module.

384 |Frequency Selective Surface Simulator
This app demonstrates the following:• Designing an app for small screens such as smartphones• User-interface navigation with a top menu typically used on websites• Geometry parts and parameterized geometries• Visualizing periodicity of a geometry with material rendering• Warning messages on icons when properties are not updated• Sending an email with a report attached when the computation is finished

Frequency selective surfaces (FSS) are periodic structures that generate a bandpass
or a bandstop frequency response. They are used to filter or block RF, microwave,or, in fact, any electromagnetic wave frequency. For example, you see theseselective surfaces on the doors of microwave ovens, which allow you to view thefood being heated without being heated yourself in the process.
The app simulates a user-specified periodic structure chosen from the built-in unit
cell types. It provides five unit cell types popularly used in FSS simulations alongwith two predefined polarizations in one fixed direction of propagation that has
normal incidence on the FSS. The analysis includes the reflection and transmission
spectra, the electric field norm on the top surface of the unit cell, and the
dB-scaled electric field norm shown on a vertical cut plane in the unit cell domain.
You can change the polarization, center frequency, bandwidth, number of
frequencies, substrate thickness and its material properties, and unit cell type(circle, ring, split ring, etc.) as well as their geometry parameters, including
periodicity (cell size).

| 385This application requires the RF Module.

386 |Microstrip Patch Antenna Array Synthesizer
This app demonstrates the following:• Parameterized geometries• Visualizing material appearance, color, and texture• Multiple plots in the same window to visualize the results• Options to visualize the results with different views using check boxes

Microstrip patch antenna arrays are used in a number of industries as transceiversof radar and RF signals. This is a prime candidate for the 5G mobile network
system.
The app simulates a single slot-coupled microstrip patch antenna, fabricated on amultilayered low-temperature cofired ceramic (LTCC) substrate. When using thisapp, you will be able to simulate the far-field radiation pattern of the antenna array
and its directivity. The far-field radiation pattern is approximated by multiplying
the array factor and the single antenna radiation pattern to perform an efficient
far-field analysis without simulating a complicated full-array model.
You can also evaluate phased antenna array prototypes for 5G mobile networks
with a default input frequency of 30 GHz. You can do this by varying antenna
properties such as the geometric dimension and substrate material.

| 387

This application requires the RF Module.

Rotor Bearing System Simulator
This app demonstrates the following:• Navigation system using toggle buttons in the ribbon and Back/Forward

buttons in the settings window• Selecting predefined or user-defined materials• Using a table for input of geometry objects

The app simulates a rotor bearing system consisting of disks and bearings mounted
on a rotating shaft. An eigenfrequency analysis is performed for a range of angularspeeds, to identify critical speeds of the system.
An app of this kind is useful at an early design stage where design modifications
can be made to move critical speeds away from the operating speed of the system.
Results include whirl modes, a Campbell plot, and a list of critical speeds.

388 |This application requires the Structural Mechanics Module and the
Rotordynamics Module.

Si Solar Cell with Ray Optics
This app demonstrates the following:• Multiple components (1D and 3D) in a single app• Using the same choice list in the app as in the model using Data Accessfunctionality• Output numerical results for a specific time step using a combo box

The app combines the Ray Optics Module and the Semiconductor Module toillustrate the operation of a silicon solar cell at a location specified by the user. The
Ray Optics Module computes the average illumination over a day of the year. The
Semiconductor Module computes the normalized output characteristics of a solar
cell with design parameters specified by the user. The normalized output
characteristics is then multiplied by the computed average illumination to obtain| 389

the output characteristics of the cell at the specified date and location, assuming
simple linear relationship between the output and the illumination.

390 |Beam Section Calculator
This app demonstrates the following:• Reading and importing data from an Microsoft® Excel-file• Exporting data to an Microsoft ® Excel-file

The app computes the beam section properties and true stress distribution in adesignated steel beam section. A broad range of American and European beam
standards are available. It uses LiveLink™ for Excel® to read and store the beamdata in Excel® worksheets.
This application requires the Structural Mechanics Module and LiveLink™ for
Excel®. A version of this app is also provided without Microsoft® Excel
functionality.

Bike Frame Analyzer
This app demonstrates the following:• Connecting an app to a SOLIDWORKS® session• Setting a maximum allowed value which the solution is compared to• Selecting predefined or user-defined materials• Changing boundary conditions with a combo box using methods

The app computes the stress distribution and the deformation of a bike frame
based on user configurable loads and constraints. It leverages LiveLink™ for| 391

SOLIDWORKS® to load the geometry, and to update the frame dimensions forstudying their effect on the results.
This application requires the Structural Mechanics Module and LiveLink™ for
SOLIDWORKS®.

392 |Fiber Simulator
For almost all commercial optical fiber types, the design consists of a concentric
layer structure with the inner layer(s) forming the core and the outer layer(s)forming the cladding. Since the core has a higher refractive index than thecladding, guided modes can propagate along the fiber.
This application performs mode analyses on concentric circular dielectric layer
structures. Each layer is described by an outer diameter and the real and imaginaryparts of the refractive index. The refractive index expressions can include a
dependence on both wavelength and radial distance. Thus, the simulator can beused for analyzing both step-index fibers and graded-index fibers. These fibers canhave an arbitrary number of concentric circular layers. Computed results include
group delay and dispersion coefficient.
This application requires the Wave Optics Module.

| 393

Plasmonic Wire GratingThis app demonstrates the following:• Choice of different user interface layouts for computer/tablet or

smartphone• Custom background image and color• Graphics appearance with custom top color and bottom color• Custom position of the graphics toolbar

This application computes diffraction efficiencies for the transmitted and reflected
waves (m = 0) and the first and second diffraction orders (m = ±1 and ±2) asfunctions of the angle of incidence for a wire grating on a dielectric substrate. The
incident angle of a plane wave is swept from normal incidence to grazing
incidence. The application also shows the electric field norm plot for multiple
grating periods for a selected angle of incidence.
This application requires the Wave Optics Module.

Polarizing Beam Splitter
A Gaussian beam is incident on a 45-degree thin-film stack embedded in glassmaterial prisms. The thin-film stack is designed from alternating high and low
refractive index materials. The wave will be refracted at the Brewster angle at eachinternal interface. Thus, mainly p-polarized waves (polarization in the plane ofincidence) will be transmitted, whereas mainly s-polarized waves (polarization

394 |orthogonal to the plane of incidence) will be reflected. Changing the spot radius
for the Gaussian beam modifies the polarization discrimination.
The reflectance and transmittance spectra are calculated for different Gaussian
beam spot radii.
The app automatically calculates the phase expressions necessary for theElectromagnetic Waves, Beam Envelopes interface, when the user changes thedesign parameters.
This application requires the Wave Optics Module.

| 395

396 |

Index1D array 153

Aapplication example

2D array 154

beam section calculator 391

3D coordinates 277

B-H curve checker 358

About dialog box 40

concentric tube heat exchanger 370

about to shutdown event 140

equivalent properties of periodic mi-action 61, 64, 139

crostructures 371

Activation Condition 157

fiber simulator 393

activation condition 237, 244

frequency selective surface simulator

active card selector 266

385

Add New Choice List 157

helical static mixer 353

Add New Form Choice List 157

induction heating of a steel billet 359

add-in 128, 210, 211

li-ion battery impedance 364

Add-in Libraries 214

li-ion battery pack designer 363

add-on products 10, 352

lithium battery designer 362

alert 203, 337

microstrip patch antenna array syn-aligning form objects 111, 120

thesizer 387

animation 76, 86

mixer 377

appearanceorgan pipe designer 361

button object 74

plasmonic wire grating 394

forms 50, 52

Si solar cell with ray optics 389

graphics object 76

transmission line calculator 354

input field object 99

truck mounted crane analyzer 379

multiple form objects 59

tubular reactor 356

table 292

tuning fork 357

text 58

water treatment basin 366

append unit from unit set 162

Application Gallery 28

append unit to number 95, 297

Application Libraries 10, 27, 28, 44, 352

application

Application Librarysaving 309

COMSOL Server 32

Application Argument 13, 129

application object 170

Application Builder 20

Application Programming Guide 11,

desktop environment 12, 19
window 12, 15, 17
Application Builder Reference Manual
11, 217

170, 199

application tree 12, 15, 17
applications
publishing 42
applications folder 10, 28, 352| 397

apply changes 23
arguments
input and output 195

cell margins 119, 126
cells

arranging form objects 111

merging 118

array 153

splitting 118

1D 153
2D 154check box object 109, 144, 152, 174,
193, 225

2D, interactively defining 155

check syntax 183

syntax 154

choice list 62, 146, 156, 157, 230, 234,

array input object 144, 276
auto complete 190
Automatic Notation 260
B273

background color 52
background image 52
BMP-file 218
Boolean variable 150, 152, 153, 225
conversion 344
Boundary Point Probe 92, 169
breakpoint 197
browser
web 31, 131
built-in method library 331
button 63, 75, 109, 193
command sequence 64
icon 63
keyboard shortcut 64
on click event 63, 64
size 63, 113
style 63
text 113
tooltip 64
buttons tab, New Form wizard 48

239, 247, 248, 281, 282, 289, 290,
338

clear selection
graphics 80
click-through agreement 39
clipboard 252, 260, 305
close application icon 140
Close brackets automatically 189
code completion 190
tooltip 191
code folding 189
color
material 80
selection 80
column settings 117, 125
combo box object 109, 144, 150, 156,
159, 229

command line 129
command sequence 18, 48, 49, 64, 67,
68, 75, 85, 137, 139, 143, 170, 194,
195, 219, 295, 303

comments
toggle on and off 188
common, file scheme 311, 326

C

C libraries
external 340
CAD-file import 270, 311, 313
cancel shutdown 140
card 265card stack object 109, 150, 151, 265,

398 |compatible with physical quantity, unit
dimension check 96
compatible with unit expression, unit
dimension check 96
Compilerbutton 36

Source 95

node 37
compiler 10, 23, 36

Create New Form Declaration and Use

complex numbers 260

It as Source 95

component syntax 189

creating

computation time 276

forms 16, 44

expected 102, 273, 275

methods 18

last 102, 275, 343

CSV file 151, 261, 295

COMSOL Client 10, 25, 26, 31, 33

curly brackets 189

file handing 307
running applications in 33, 307
COMSOL Compiler 10, 23, 36
COMSOL Desktop environment 12,
19

COMSOL Multiphysics 10, 23, 24, 29,
30, 33, 126, 170, 199, 254, 257, 258

COMSOL Runtime 37
COMSOL Server 10, 23, 25, 26, 28, 30,
31, 33, 34, 311

manual 36
COMSOL Software License Agreement 42
confirm 203, 337
Continue 197
Convert to Form Method 18, 69, 170,
194

Convert to Local Method 18, 69, 170,
194

Convert to Method 18, 68, 70, 170, 172,
194, 315

Coordinate 166, 168
Copy Table and Headers to Clipboard
260

copying
forms and form objects 126, 305
objects 56
rows or columns 118
Create Local Method 193
Create Local Variable 192
Create New Declaration and Use It as

custom settings window 127
D

DAT file 151, 261, 295
Data Access 106, 178, 182
data change 61, 144, 195, 227, 228, 351
data display object 98, 101, 109
information node 275
tooltip 104
data file 151, 261, 295
Data picking 168
data picking 91, 168
data validation 95, 162date 342
Debug Log 198
debug log window 198, 340
debugging 197, 340
Decimal Notation 260
Declaration and Use it as Source 148
Declarations 13, 146, 148
form 95, 146, 147
global 95
local 95
declarations node 225
delete button 56, 67, 271
deleting an object 56
Depth Along Line 169
derived values 102, 259
description text
Boolean variable 227
derived value 100
desktop icon 24, 38, 131
desktop shortcut 24, 131| 399

Developer tab 18, 104, 128, 180, 206

Evaluation 2D 168

dialog box 337

Evaluation 3D 168

disable form object 338

evaluation tables 168

display name, for choice list 156, 159,

event 61, 139, 144, 193, 195, 236

231, 282, 289, 338

displayed text 58

button on click 64

Domain Point Probe 169

for multiple form objects 59, 144domain point probe 92

form 144

double variable 150, 152, 153

form object 144

conversion 344

keyboard shortcut 64

drag and drop, form objects 56

local 139

duplicating

node 140

rows or columns 118

edit local method 195
edit node 65, 176, 178
Editor Tools 176
editor tools 61, 179, 233, 234
window 17
editor tree 62, 65, 79, 176, 308, 310
element size 108
change 245
email 301
class 334
methods 334
email attachment
export 334
report 334
table 334
embedded, file scheme 217, 220, 311,
318

Enable code folding 189
enable form object 338
enabled state, for form objects 74
Engineering Notation 260
equation object 249
error message, data validation 96, 98
errors and warnings window 183

400 |global 13, 110, 139

double, data validation 97

duplicating an object 56
Eabout to shutdown 140

on close 145
on data change 61, 144, 195, 227,
228, 351

on load 61, 145
on startup 140
slider 298, 300
Events 13
example applicationbike frame analyzer 391
charge exchange cell simulator 378
corrugated circular horn antenna 383
effective nonlinear magnetic curves
calculator 360
finned pipe 372
forced air cooling with heat sink 373
general parameter estimation 380
geothermal heat pump 381
inline induction heater 374
polarizing beam splitter 394
rotor bearing system simulator 388
solar dish receiver designer 382
thermoelectric cooler 375
Excel® file 151, 261, 295
executable 10, 23, 36
explicit selection 88, 89
exponent, number format 102

exportform 15, 52
Declarations 146

email attachment 334
export button, results table 260

local 54

export node 307, 319

form collection 109, 134, 263

Export Selected Image File 218

Form editor 20

exportingdesktop location 12
overview 15

results 307, 319

Fexternal C libraries 340

preferences 19, 55

extracting subform 113

using 51
form event 144

file

form method 18, 139, 144, 170

commands 308

form object 15, 55, 61, 221

declaration 158

event 144

destination 271, 313

with associated methods 174

download 33, 309

form reference 263

import 65, 144, 158, 217

Form tab, in ribbon 15

menu 138

form window 15

methods 332

Form wizard 61, 62, 100

opening 308

Forms 13saving 309

Full Precision 260

types 271

function 17

upload 33, 309
file browser 324
file import object 144, 158, 217, 270,
307, 312

file open
system method 334
file schemeG

geometry 30, 48, 65, 76, 82, 91, 284,
305, 314, 316, 337

import 270, 311, 313
operations 254, 257, 258
Geometry Entity Level 169
geometry node 65

common 311, 326

get 347

embedded 217, 220, 311, 318

GIF-file 218

syntax 217

global evaluation 102, 265

temp 311

global event 13, 139

upload 158, 311, 316, 319

global method 18, 144, 170

user 311, 326

global parameter 202

filename 271, 313, 332

Go to Method 18

files library 220

go to method 68, 172

Find 184

graphics 69

fit, row and column setting 113, 117

clearing contents 82

fixed, row and column setting 113, 117

commands 79

for statement 201

hardware acceleration 42| 401

hardware limitations 81

object 252

object 46, 48, 75, 144, 337

Preview 218

plot group 82
Source for Initial Graphics Content
166

source for initial graphics content 75
tab, New Form wizard 48
toolbar 82, 109

H

thumbnail 28
Images library 218
Immediately
Store changes 74
importfile 65, 144, 158, 217, 271, 313

using multiple objects 81

Indent and Format 188

view 79, 85, 339

Indent and format automatically 189

graphics data 92, 146, 166

information card stack object 109, 273

grid layout mode 33, 52, 101, 110

information node 275

grid lines, sketch layout mode 111

inherit columns 125

grow, row and column setting 113, 117

initial size, of main window 134

growth rules 113

initial values, of array 153

Home tab, in ribbon 44
HTMLcode 251
report 251, 327
HTTP and HTTPS protocols 301
hyperlink object 300

initialize
parameter 70
variable 70
Initializing Installer progress window 39
input arguments 129, 195
input field object 93, 109, 144, 150, 162
adding 93

Iicon 218, 303
button 63
close application 140
command 65
desktop 24, 38, 131
graphics 76

information node 275
text object 100
tooltip 94
unit object 100
Inputs 13, 129
inputs/outputs tab, New Form wizard

help 97
main window 133
menu item 137
method 174
ribbon item 137
toolbar 303
if statement 201
ignore license errors 25
image
background 52
formats 218

402 |

46

insertingform objects 60, 61
rows and columns 113, 116
rows or columns 118
integerdata validation 97
variable 150, 152, 153
variable conversion 344
itemmenu 136, 193

ribbon 138
toolbar 302
J

Java utility class 217
Java® programming language 170, 199
JPG file 29
JPG-file 218

marginscell 119, 126
material 237
material color and texture 80
math functions 201
menu 136, 138
bar 134, 135

K

keyboard shortcut 19, 61, 139, 178, 190,
192, 199, 328

event 64, 137, 303
knob object 298
Llanguage elements window 17, 175, 199
LaTeX 100, 103, 249
layout mode 52, 110

toggle item 136, 222
menu toggle item 109
merging cells 113, 118
mesh 48, 76, 82, 108
change element size 245
size 108

layout options, form collection 263

meshing 254, 257, 258

layout template 16, 45, 55

message log object 258, 337

Libraries 14

method 14, 17, 59, 68, 75, 146, 170, 331

libraries node 217, 252

event 140, 144

license agreement 42

form 18, 139, 144, 170

license errors

form object 174

ignoring 25

global 18, 144, 170

Line Entry Method 169
line object 250
list box object 109, 144, 150, 156, 159,
287

local 18, 61, 69, 139, 144, 145, 170,
174, 193, 227, 231, 305

Model Builder 203
window 17

LiveLink™ for Excel® 151, 261, 295

Method Call 204, 211

LiveLink™ products 34

Method editor 20, 331

local event 139

desktop location 12

local form 54

overview 17

local method 18, 61, 69, 139, 144, 145,

Preferences 189

170, 174, 193, 195, 227, 231, 305

using 170

local variable 192

Method tab, in ribbon 17

log object 257

method, called from the Model Builder

logo image 76
low-resolution displays 33
Mitem 75, 109, 136, 193

main form 134
Main Window 13
main window 134, 254
node 133

203

Methods 14
Microsoft® Word® format 325
minimum size
form objects 119
Model Builder| 403

method 190, 203

new method 18

model commands 310

notationmodel data access 109, 142, 305

data display number format 102

Model Expressions 185

unit 102

model expressions window 17

number format 98, 102

model object 170, 199, 331

number of rows and columns 113

model tree node, controlling if active

numerical validation 97, 162

204

O

model utility methods 331

on click event, button 63

move down

on close event 145

command sequence 67

on data change event 61, 144, 195, 227,

table 294

228, 351

move upon load event 61, 145

command sequence 67

On request

table 294

Store changes 74

MP4 file 253

on startup event 140

MPH file 14, 23, 24, 26, 30, 44, 49, 217,

open file 308

310, 340

OpenGL graphics hardware accelera-

multiline text 101

tion 42

multiple form objects

operating system command line 129

selecting 59, 144N

operators 200

nameoptimization 365

button 63

orthographic projection 79

check box 227

OS commands 334

choice list 156

output arguments 195

form 52

Output directoryform object 59
graphics object 75
menu 137
method 188
shortcut 164
variable 149
named selection 88
new element value 153
new form 16
New Form wizard 60, 100
buttons tab 48
graphics tab 48
inputs/outputs tab 46

404 |OGV file 253

for compiled applications 37
Ppanes 263
parameter 17, 47, 69, 94, 96, 150, 202,
305, 347

combo box object 229
declarations 13, 146
events 13, 139
input field object 93
method 182, 201
slider object 297, 299
text label object 100
parentheses 189

password protected application 30
pasting
form objects 56
forms and form objects 127
image 252rows or columns 118
pixels 58, 110
play sound 33, 219, 334
plot 48, 65, 75, 82, 152, 226, 232, 290,
302, 315, 323, 337

plot geometry command 65
plot group 69, 152
PNG file 29, 218
PNG-file 218
Point Being Modified 169
Polar Complex Numbers 260
position and size 58, 110, 112
multiple form objects 59
positioning form objects 55
precedence, of operators 200
precision 260
precision, number format 102
preferences 19, 55, 189, 311, 312
for compiled applications 41
security 30
Preview
image 218
preview form 23
printing
graphics 80, 340
Probe 169
procedure 17
Programming Reference Manual 11
progress 254, 342
progress bar object 254, 342
progress bar, built in 254
progress dialog box 256, 342
publishing applications 42
Q

Find 184
R

radio button object 109, 144, 156, 159,
280

Record Code 180
recording code 180
Rectangular Complex Numbers 260
recursion 196
regular expression 97
removing
password protection 30
rows and columns 113, 116
rows or columns 118
report 349, 352
creating 307, 319, 325, 326
creating automatically 204
email attachment 334
embedding 251
HTML 251, 327
image 29
node 307, 319, 326
request 203, 337
reset current view 79, 85
resizable graphics 33
resizing form objects 56
Results Evaluation 166, 168
results table object 259, 338
ribbon 134, 138
item 110, 138section 138
tab 138
toggle item 109, 138, 222
row settings 116
run application 23, 25
running applications
compiled 36
in a web browser 31, 307
in the COMSOL Client 33
runtime 37

Quick Access Toolbar 23

| 405

S

save
application 49
running application 26

shutdown
cancel 140

save application command 309

sketch grid 111

save as 340

sketch layout mode 52, 101, 110

save file 309

slider object 109, 144, 296

Scalar 150

smartphones

scalar variable 150, 230, 265, 297, 299

running applications on 33

scene light 79, 340

software rendering 42

Scientific Notation 260

solving 254, 257, 258

security settings 30

sound

select allgraphics 80
selection 48, 76, 82
explicit 89

play 219
Sounds library 218
Source for Initial Graphics Content 166,168

selection colors 80

spacer object 303

selection input object 89, 283

special characters 131

selections 88

splash screen 38

selectNode method 204

splitting cells 113, 118

separatorstatemenu 136
ribbon 138
toolbar 136, 302
separators
CSV, DAT, and TXT files 295

enabled, for form objects 74
visible, for form objects 74
status bar 254
Step 197
Stop 197

set value command 108

Stop Recording 182

Settings Form 128, 203, 211

stopping a method 199

Settings Forms 127

Store changes 74

settings window

string variable 13, 70, 139, 141, 150, 153,

customized 127
Form editor 12, 15
Method editor 17
shortcutdesktop 24, 131
shortcuts 146, 164
use 185229, 231, 239, 263, 274, 286, 315

conversion 344
methods 346
subroutine 17
Switch to Model Builder and Activate
Data Access 95
syntax errors 183

Show as Dialog command 70

syntax highlighting 187, 190

Show Dialog 128

system methods 334

show form command 71

406 |Show in Model Builder 128

OS commands 334

T

table

graphics 82, 109

email attachment 334

item 109, 302

table object 144, 153, 291, 337

separator 136, 302

tables, model tree 259

tooltiptablets

button 64

running applications on 33

data display object 104

Target for Data Picking 91, 168

input field object 94

temp, file scheme 311

method editor 191

template 16, 45, 55

slider object 297, 299

temporary file 324

toolbar button 303

test application 23, 25

unit mismatch 96

test in web browser 23transparency 79, 340

text 137

TXT file 150, 261, 295

text color 52
text file 150, 261, 295
text label object 93, 100, 102
text object 109, 144, 286
information node 275
Theme 190
Themes 13
Themes node 50
thumbnail image 28
time 342
time parameter
combo box object 234
timestamps 258
title
form 52
main window 133
menu 137
toggle button 109, 222
size 113
text 113
toggle item
menu 109, 136, 222
ribbon 109, 138, 222
toolbar 302
toolbar 136, 260, 302
button, table object 294

U

Unicode 100, 103
unitchanging using unit set 159
data display 102
dimension check 96, 162
expression 96
groups 159
lists 159
object 93, 100
Unit Groups 159
Unit Lists 159
Unit Set 159
unit set 97, 146, 248, 282, 290
Untitled.mph 26
uploadfile scheme 158, 311, 316, 319
URL 131, 251, 301
use as source
array input object 278
card stack object 266
check box object 227
combo box object 230
data display object 102
declaration 148
explicit selection 90, 283
graphics object 75| 407

information card stack object 274

graphics 79, 85, 339

input field object 93

reset current 79, 85

list box object 288

View all code 189

radio button object 281

visible state, for form objects 74

results table object 260

volume maximum 102

selection input object 90, 283

W WAV-file 218

slider object 297, 299

web browser 10, 26, 31, 131

table object 291

file handling 307

text object 286

web page

Use component syntax 189

hyperlink 301

use shortcuts 185, 186

web page object 251

user

WebGL 31

file scheme 311, 326

WebM file 253

user interface layout 15

while statement 201

username 334
Vwith statement 189, 201, 346

Value 156, 159with statements 189

variable 13, 146, 182

wrap text

accessing from method 201
activation condition 157
Boolean 152, 153, 225
declaration 13, 146
derived values 102
double 152, 153
events 13, 139, 141
find and replace 184
input field object 93
integer 152, 153
name completion 190
scalar 230, 265, 297, 299
slider object 297, 299
string 150, 153, 229, 231, 263, 274,
286

text label object 100
video
controls 254
player 254
video object 253
view
go to default 3D 85

408 |text label object 101
Zzoom extents 76, 79, 290, 315, 340