LiveLink

for Matlab
Users Guide

VERSION 4.4

TM

LiveLink for MATLAB Users Guide

20092013 COMSOL
Protected by U.S. Patents 7,519,518; 7,596,474; 7,623,991; and 8,457,932. Patents pending.
This Documentation and the Programs described herein are furnished under the COMSOL Software License
Agreement (www.comsol.com/sla) and may be used or copied only under the terms of the license
agreement.
COMSOL, COMSOL Multiphysics, Capture the Concept, COMSOL Desktop, and LiveLink are either
registered trademarks or trademarks of COMSOL AB. MATLAB is a registered trademark of The
MathWorks, Inc.. All other trademarks are the property of their respective owners, and COMSOL AB and
its subsidiaries and products are not affiliated with, endorsed by, sponsored by, or supported by those or the
above non-COMSOL trademark owners. For a list of such trademark owners, see www.comsol.com/tm.
Version:

November 2013

COMSOL 4.4

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 at www.comsol.com/support/case.
Other useful links include:
Support Center: www.comsol.com/support
Product Download: www.comsol.com/support/download
Product Updates: www.comsol.com/support/updates
COMSOL Community: www.comsol.com/community
Events: www.comsol.com/events
COMSOL Video Center: www.comsol.com/video
Support Knowledge Base: www.comsol.com/support/knowledgebase
Part number: CM020008

C o n t e n t s
Chapter 1: Introduction
About LiveLink for MATLAB

Help and Documentation

Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . 9
Where Do I Access the Documentation and the Model Libraries?

. . . . 10

Chapter 2: Getting Started

The Client-Server Architecture

16

Running COMSOL with MATLAB

17

Starting COMSOL with MATLAB on Windows / Mac OSX / Linux . . . . 17

Connecting the COMSOL Server and MATLAB Manually . . . . . . . . 18
Changing the MATLAB Version . . . . . . . . . . . . . . . . . . 20
Calling a MATLAB Function from the COMSOL Desktop

21

Chapter 3: Building Models

The Model Object

24

Important Notes About the Model Object . . . . . . . . . . . . . 24

The Model Object Methods . . . . . . . . . . . . . . . . . . . 25
The General Utility Functionality . . . . . . . . . . . . . . . . . 25
The Model History . . . . . . . . . . . . . . . . . . . . . . 26
Loading and Saving a Model . . . . . . . . . . . . . . . . . . . 27
Sharing the model between the COMSOL Desktop and the MATLAB
prompt . . . . . . . . . . . . . . . . . . . . . . . . . 29
Working with Geometry

31

The Geometry Sequence Syntax . . . . . . . . . . . . . . . . . 31

Displaying the Geometry . . . . . . . . . . . . . . . . . . . . 32
Working with Geometry Sequences . . . . . . . . . . . . . . . . 33
Exchanging Geometries with the COMSOL Desktop . . . . . . . . . 40

Importing and Exporting Geometries and CAD Models from File . . . . . 41

Retrieving Geometry Information

. . . . . . . . . . . . . . . . 42

Modeling with a Parameterized Geometry . . . . . . . . . . . . . 43

Images and Interpolation Data . . . . . . . . . . . . . . . . . . 46
Working with Meshes

52

The Meshing Sequence Syntax . . . . . . . . . . . . . . . . . . 52

Displaying the Mesh . . . . . . . . . . . . . . . . . . . . . . 53
Mesh Creation Functions . . . . . . . . . . . . . . . . . . . . 54
Importing External Meshes and Mesh Objects . . . . . . . . . . . . 73
Measuring Mesh Quality . . . . . . . . . . . . . . . . . . . . 74
Getting Mesh Statistics Information . . . . . . . . . . . . . . . . 75
Getting and Setting Mesh Data . . . . . . . . . . . . . . . . . . 76
Modeling Physics

81

The Physics Interface Syntax . . . . . . . . . . . . . . . . . . . 81

The Material Syntax . . . . . . . . . . . . . . . . . . . . . . 84
Modifying the Equations . . . . . . . . . . . . . . . . . . . . 85
Adding Global Equations . . . . . . . . . . . . . . . . . . . . 86
Defining Model Settings Using External Data File . . . . . . . . . . . 88
Access the User-Defined Physics Interface . . . . . . . . . . . . . 89
Creating Selections

91

The Selection Node . . . . . . . . . . . . . . . . . . . . . . 91

Coordinate-Based Selections

. . . . . . . . . . . . . . . . . . 92

Selection Using Adjacent Geometry . . . . . . . . . . . . . . . . 95

Displaying Selections . . . . . . . . . . . . . . . . . . . . . . 97
Computing the Solution

100

The Study Node . . . . . . . . . . . . . . . . . . . . . . 100

The Solver Sequence Syntax . . . . . . . . . . . . . . . . . . 101
Run the Solver Sequence . . . . . . . . . . . . . . . . . . . 102
Adding a Parametric Sweep . . . . . . . . . . . . . . . . . . 103
Adding a Job Sequence . . . . . . . . . . . . . . . . . . . . 104
Plot While Solving. . . . . . . . . . . . . . . . . . . . . . 104
Analyzing the Results

106

The Plot Group Syntax . . . . . . . . . . . . . . . . . . . . 106

Displaying The Results . . . . . . . . . . . . . . . . . . . . 107
The Data Set Syntax . . . . . . . . . . . . . . . . . . . . . 110
The Numerical Node Syntax. . . . . . . . . . . . . . . . . . 111
Exporting Data . . . . . . . . . . . . . . . . . . . . . . . 112

4 |

CHAPTER :

C h a p t e r 4 : Wo r k i n g W i t h M o d e l s
Using MATLAB Variables in Model Settings

116

The Set and SetIndex Methods . . . . . . . . . . . . . . . . . 116

Using a MATLAB Function to Define Model Properties . . . . . . . . 117
Extracting Results

119

Extracting Data From Tables . . . . . . . . . . . . . . . . . . 119

Extracting Data at Node Points . . . . . . . . . . . . . . . . . 120
Extracting Data at Arbitrary Points . . . . . . . . . . . . . . . 123
Evaluating an Expression at Geometry Vertices . . . . . . . . . . . 126
Evaluating an Integral. . . . . . . . . . . . . . . . . . . . . 129
Evaluating a Global Expression . . . . . . . . . . . . . . . . . 131
Evaluating a Global Matrix . . . . . . . . . . . . . . . . . . . 133
Evaluating a Maximum of Expression . . . . . . . . . . . . . . . 133
Evaluating an Expression Average . . . . . . . . . . . . . . . . 135
Evaluating a Minimum of Expression . . . . . . . . . . . . . . . 137
Evaluating Expressions on Particle Trajectories . . . . . . . . . . . 139
Running Models in a Loop

142

The Parametric Sweep Node

. . . . . . . . . . . . . . . . . 142

Running Model in a Loop Using the MATLAB Tools . . . . . . . . . 142

Running Models in Batch Mode

145

The Batch Node . . . . . . . . . . . . . . . . . . . . . . 145

Running an M-file in Batch Mode . . . . . . . . . . . . . . . . 145
Running an M-file in Batch Mode Without Display. . . . . . . . . . 146
Working with Matrices

147

Extracting System Matrices . . . . . . . . . . . . . . . . . . 147

Set System Matrices in the Model . . . . . . . . . . . . . . . . 150
Extracting State-Space Matrices. . . . . . . . . . . . . . . . . 155
Extracting Solution Information and Solution Vectors

160

Obtaining Solution Information . . . . . . . . . . . . . . . . . 160

Retrieving Solution Information and Solution Data Sets Based on
Parameter Values . . . . . . . . . . . . . . . . . . . . . 162
Extracting Solution Vector. . . . . . . . . . . . . . . . . . . 165
Retrieving Xmesh Information

167

The Extended Mesh (Xmesh) . . . . . . . . . . . . . . . . . 167

Extracting Xmesh Information . . . . . . . . . . . . . . . . . 167

Navigating the Model

170

Navigating the Model Object Using a GUI. . . . . . . . . . . . . 170

Navigating The Model Object At The Command Line . . . . . . . . 174
Finding Model Expressions . . . . . . . . . . . . . . . . . . 175
Getting Feature Model Properties. . . . . . . . . . . . . . . . 176
Getting Model Expressions . . . . . . . . . . . . . . . . . . 176
Getting Selection Information . . . . . . . . . . . . . . . . . 176
Handling Errors and Warnings

177

Errors and Warnings. . . . . . . . . . . . . . . . . . . . . 177

Using MATLAB Tools to Handle COMSOL Exceptions . . . . . . . . 177
Displaying Warnings and Errors in the Model . . . . . . . . . . . 177
Improving Performance for Large Models

179

Setting Java Heap Size . . . . . . . . . . . . . . . . . . . 179

Disabling Model Feature Update . . . . . . . . . . . . . . . . 180
Disabling The Model History

. . . . . . . . . . . . . . . . . 181

Creating a Custom GUI

182

COMSOL 3.5a Compatibility

183

Chapter 5: Calling MATLAB Functions

The MATLAB Function Feature Node

186

Defining a MATLAB Function in the COMSOL Model . . . . . . . . 186

Setting the Function Directory Path in MATLAB . . . . . . . . . . 190
Adding a MATLAB Function with the COMSOL API Syntax . . . . . . 191
Function Input/Output Considerations . . . . . . . . . . . . . . 191
Updating Functions . . . . . . . . . . . . . . . . . . . . . 192
Defining Function Derivatives . . . . . . . . . . . . . . . . . 192

Chapter 6: Command Reference

6 |

CHAPTER :

Summary of Commands

196

Commands Grouped by Function

197

Introduction
This guide introduces you to LiveLink for MATLAB, which extends your
COMSOL modeling environment with an interface between COMSOL
Multiphysics and MATLAB. The COMSOL API Reference Manual provides
additional documentation of the API.
In this chapter:
About LiveLink for MATLAB
Help and Documentation

About LiveLink for MATLAB

LiveLink for MATLAB connects COMSOL Multiphysics to the MATLAB scripting
environment. Using this functionality you can do the following:

Set Up Models from a Script

LiveLink for MATLAB includes the COMSOL API, which has all the necessary
functions and methods to implement models from scratch. For each operation done in
the COMSOL Desktop there is a corresponding command that is entered at the
MATLAB prompt. It is a simplified syntax based on Java and does not require any
Java knowledge. The easiest way to learn this syntax is to save the model as an M-file
directly from the COMSOL Desktop. Read more about building a model using the
command line in the section Building Models.

Use MATLAB Functions in Model Settings

Use LiveLink for MATLAB to set model properties with a MATLAB function. For
example, define material properties or boundary conditions as a MATLAB routine that
is evaluated while the model is solved. Read more in Calling MATLAB Functions.

Leverage MATLAB Functionality for Program Flow

Use the API syntax together with MATLAB functionality to control the flow of your
programs. For example, implement nested loops using for or while commands,
implement conditional model settings with if or switch statements, or handle
exceptions using try and catch. Some of these operations are described in Running
Models in a Loop and Handling Errors and Warnings.

Analyze Results in MATLAB

The API wrapper functions included make it easy to extract data at the command line.
Functions are available to access results at node points or arbitrary locations. You can
also get low level information about the extended mesh, such as finite element mesh
coordinates, and connection information between the elements and nodes. Extracted
data are available as MATLAB variables ready to be used with any MATLAB function.
See Extracting Results and Retrieving Xmesh Information.

Create Custom Interfaces for Models

Use the MATLAB Guide functionality to create a user-defined graphical interface that
is combined with a COMSOL model. Make your models available for others by
creating graphical user interfaces tailored to expose settings and parameters of your
choice.

8 |

CHAPTER 1: INTRODUCTION

He lp a nd Do c u men t at i on
In this section:
Getting Help
Where Do I Access the Documentation and the Model Libraries?

Getting Help
COMSOL Multiphysics and LiveLink for MATLAB have several sources of help and
information.
T H E I N T RO D U C T I O N T O L I VE L I N K F O R M AT L A B

To get started with LiveLink for MATLAB, it is recommended that you read the
Introduction to LiveLink for MATLAB. It contains detailed examples about how
to get you started with the product.
ONLINE DOCUMENTATION AND OTHER RESOURCES

Access the on-line documentation with the function mphdoc.

Read this user guide to get detailed information about the different parts of the
model object and how these are accessed from MATLAB. In the section Command
Reference the function available for use with LiveLink for MATLAB are
described.
The COMSOL API Reference Manual contains reference documentation that
describes the methods in the model object.
M-FILES

Save models as an M-file. Use the COMSOL Desktop to get your first model
implemented using the COMSOL API.
Set up the model using the graphical user interface, then save the model as an M-file.
Next go to the File menu and select Save, in the Save window locate Save as type list
and select Model file for MATLAB (*.m). This generates an M-function that can be run
using COMSOL with MATLAB.
THE MODEL LIBRARIES WINDOW

Study the LiveLink for MATLAB model library. LiveLink for MATLAB includes
a model library with detailed example models. Use the function mphmodellibrary at

HELP AND DOCUMENTATION

the command line to get a list of available models. The following are some models that
can help get you started.

Model Examples
Learn how to activate and deactivate domains alternatively during a transient
analysis. See the model Domain Activation and Deactivation (model name
domain_activation_llmatlab).
Homogenization in a Chemical Reactor (model name
homogenization_llmatlab) shows how to simulate a periodic homogenization
process in a space-dependent chemical reactor model. This homogenization
removes concentration gradients in the reactor at a set time interval.
Convective Heat Transfer with Pseudo-Periodicity (model name
pseudoperiodicity_llmatlab) simulates convective heat transfer in a channel
filled with water. To reduce memory requirements, the model is solved repeatedly
on a pseudo-periodic section of the channel. Each solution corresponds to a
different section, and before each solution step the temperature at the outlet
boundary from the previous solution is mapped to the inlet boundary.
Temperature Distribution in a Vacuum Flask (model name
vacuum_flask_llmatlab) shows how to use the MATLAB function callback. This
example solves for the temperature distribution inside a vacuum flask with hot
coffee.
Electrical Heating of a Busbar Solved with LiveLink for SolidWorks and
LiveLink for MATLAB (model name busbar_llsw_llmatlab) performs
geometry optimization using COMSOL Multiphysics, MATLAB, and
SolidWorks.

Where Do I Access the Documentation and the Model Libraries?

A number of Internet resources provide more information about COMSOL, including
licensing and technical information. The electronic documentation, topic-based (or

10 |

CHAPTER 1: INTRODUCTION

context-based) help, and the Model Libraries are all accessed through the COMSOL
Desktop.
If you are reading the documentation as a PDF file on your computer, the
blue links do not work to open a model or content referenced in a
different guide. However, if you are using the Help system in COMSOL
Multiphysics, these links work to other modules (as long as you have a
license), model examples, and documentation sets.
THE DOCUMENTATION AND ONLINE HELP

The COMSOL Multiphysics Reference Manual describes all core physics interfaces
and functionality included with the COMSOL Multiphysics license. This book also has
instructions about how to use COMSOL and how to access the electronic
Documentation and Help content.

Opening Topic-Based Help

The Help window is useful as it is connected to many of the features on the GUI. To
learn more about a node in the Model Builder, or a window on the Desktop, click to
highlight a node or window, then press F1 to open the Help window, which then
displays information about that feature (or click a node in the Model Builder followed
). This is called topic-based (or context) help.
by the Help button (
To open the Help window:
In the Model Builder, click a node or window and then press F1.
On any toolbar (for example, Home or Geometry), hover the mouse over
a button (for example, Browse Materials or Build All) and then press F1.
From the File menu, click Help (

).

In the upper-right part of the COMSOL Desktop, click the (

button.

To open the Help window:

In the Model Builder, click a node or window and then press F1.
On the main toolbar, click the Help (

) button.

From the main menu, select Help>Help.

HELP AND DOCUMENTATION

11

Opening the Documentation Window

To open the Documentation window:
Press Ctrl+F1.
From the File menu select Help>Documentation (

).

To open the Documentation window:

Press Ctrl+F1.
On the main toolbar, click the Documentation (

) button.

From the main menu, select Help>Documentation.

THE MODEL LIBRARIES WINDOW

Each model includes documentation that has the theoretical background and
step-by-step instructions to create the model. The models are available in COMSOL
as MPH-files that you can open for further investigation. You can use the step-by-step
instructions and the actual models as a template for your own modeling and
applications. In most models, SI units are used to describe the relevant properties,
parameters, and dimensions in most examples, but other unit systems are available.
Once the Model Libraries window is opened, you can search by model name or browse
under a module folder name. Click to highlight any model of interest and a summary
of the model and its properties is displayed, including options to open the model or a
PDF document.

The Model Libraries Window in the COMSOL Multiphysics Reference

Manual.

12 |

CHAPTER 1: INTRODUCTION

Opening the Model Libraries Window

To open the Model Libraries window (

):

From the Home ribbon, click (

) Model Libraries.

From the File menu select Model Libraries.

To include the latest versions of model examples, from the File>Help
menu, select (
) Update COMSOL Model Library.

On the main toolbar, click the Model Libraries

button.

From the main menu, select Windows>Model Libraries.

To include the latest versions of model examples, from the Help menu
select (
) Update COMSOL Model Library.

CONTACTING COMSOL BY EMAIL

For general product information, contact COMSOL at [email protected].

To receive technical support from COMSOL for the COMSOL products, please
contact your local COMSOL representative or send your questions to
[email protected]. An automatic notification and case number is sent to you by
email.
COMSOL WEBSITES

COMSOL website

www.comsol.com

Contact COMSOL

www.comsol.com/contact

Support Center

www.comsol.com/support

Product Download

www.comsol.com/product/download

Product Updates

www.comsol.com/support/updates

COMSOL Community

www.comsol.com/community

Events

www.comsol.com/events

COMSOL Video Gallery

www.comsol.com/video

Support Knowledge Base

www.comsol.com/support/knowledgebase

HELP AND DOCUMENTATION

13

14 |

CHAPTER 1: INTRODUCTION

Getting Started
In this chapter:
The Client-Server Architecture
Running COMSOL with MATLAB
Calling a MATLAB Function from the COMSOL Desktop

15

The Client-Server Architecture

LiveLink for MATLAB uses the client-server mode to connect COMSOL
Multiphysics and MATLAB. When starting COMSOL with MATLAB, two processes
are started a COMSOL server and the MATLAB desktop. The MATLAB process is
a client connected to the COMSOL server using a TCP /IP communication protocol.

The COMSOL Desktop is not involved.

You provide login information the first time COMSOL is started with MATLAB. This
information is stored in the user preferences file and is not required again when using
COMSOL with MATLAB. The same login information can be used when exchanging
the model object between the COMSOL server and the COMSOL Desktop.
The communication between the COMSOL server and MATLAB is established by
default using port number 2036. If this port is in use, port number 2037 is used
instead, and so on.
You can manually specify the port number. See the COMSOL
Installation Guide for more information on the COMSOL server
start-up properties.

The links to features described outside of this user guide do not work in
the PDF, only from the online help.

16 |

CHAPTER 2: GETTING STARTED

Running COMSOL with MATLAB

The command to run COMSOL with MATLAB automatically connects a COMSOL
process with MATLAB. You can also connect the process manually. This section this
process as well as how to change the MATLAB path in the COMSOL settings.

The System Requirements section in the COMSOL Installation Guide

lists the versions of MATLAB supported by LiveLink for MATLAB.
In this section:
Starting COMSOL with MATLAB on Windows / Mac OSX / Linux
Connecting the COMSOL Server and MATLAB Manually
Changing the MATLAB Version

Starting COMSOL with MATLAB on Windows / Mac OSX / Linux

To run a COMSOL Multiphysics model at the MATLAB prompt, start COMSOL
with MATLAB:
On Windows use the COMSOL with MATLAB shortcut icon that is created on the
desktop after the automatic installation. A link is also available in the Windows start
menu under All Programs>COMSOL 44>COMSOL 4.4 with MATLAB.
On Mac OS X, use the COMSOL with MATLAB application available in the Application
folder.
On Linux, enter the command comsol server matlab at a terminal window.

See the COMSOL Installation Guide for a complete description about

how to start COMSOL with MATLAB on these supported platforms.

The first time COMSOL with MATLAB is started, login and password
information is requested to establish the client/server connection. The
information is saved in the user preference file and is not required again.

R U N N I N G C O M S O L W I T H M AT L A B

17

To reset the login information, add the flag -login force to the icon
target path.

To reset the login information, enter the command comsol server

matlab -login force at a system command prompt.

Connecting the COMSOL Server and MATLAB Manually

Manually connecting MATLAB to a COMSOL server can be useful if you want to
start a MATLAB standalone and then connect to a COMSOL server, or if you need to
connect MATLAB and a COMSOL server running on different computers.
To manually connect MATLAB to a COMSOL server, start MATLAB and a
COMSOL server.

Starting a COMSOL Server

On Windows go to the start menu All Programs>COMSOL 44> Client Server>COMSOL
Multiphysics 4.4 server.
On Mac OS X or Linux enter comsol server at a terminal window.

Connecting MATLAB to the COMSOL Server

1 In MATLAB, add the path of the COMSOL4.4/mli directory.
2 Enter this command at the MATLAB prompt:
mphstart(<portnumber>)

- Where <portnumber> is the port used by the COMSOL server.

- If the COMSOL server is listening on the default port, 2036, the port number
does not need to be specified.
A D J U S T I N G T H E M AT L A B J AVA H E A P S I Z E

To be able to manipulate the model object and extract data at the MATLAB prompt,
you need to modify the Java heap size in MATLAB. See Improving Performance for

18 |

CHAPTER 2: GETTING STARTED

Large Models.
CON N ECT IN G MATLA B AN D TH E C OM SO L SE R VE R O N DI FF EREN T
COMPUTERS

This operation requires a Floating Network License (FNL).

To connect MATLAB and a COMSOL server that are running on different computers,
specify the IP address of the computer where the COMSOL server is running in the
function mphstart:
mphstart(<ipaddress>, <portnumber>)
<ipaddress> can also be defined with the server domain name.

The command above assume that the same user login information are set on the server
and client machine. In case the login information are not accessible from the client
machine, specify manually the user name and password to the COMSOL server with
the command:
mphstart(<ipaddress>, <portnumber>, <username>, <password>)

If the COMSOL Multiphysics installation folder cannot be found automatically, you

can specify its location manually as in the command below:
mphstart(<ipaddress>, <portnumber>, <comsolpath>)

where <comsolpath> is the path of the COMSOL installation folder.

You can also specify all the information to connect the COMSOL server within the
same command, use the following command:
mphstart(<ipaddress>, <portnumber>, <comsolpath>, ...
<username>, <password>)
IMPORTING THE COMSOL CLASS

Once MATLAB and the COMSOL server are manually connected, import the
COMSOL class by entering the following command at the MATLAB prompt:
import com.comsol.model.*
import com.comsol.model.util.*

R U N N I N G C O M S O L W I T H M AT L A B

19

Disconnecting MATLAB and the COMSOL Server

To disconnect MATLAB and the COMSOL server, run this command at the
MATLAB prompt:
ModelUtil.disconnect;

Changing the MATLAB Version

The path of the MATLAB version connected to COMSOL Multiphysics is defined
during the initial COMSOL installation. The MATLAB root path can be changed
using the Preferences dialog box:
1 From the File (Windows users) or Options menu (Mac and Linux users), select
Preferences (

).

2 In the Preferences dialog box, click LiveLink products.

3 Set the MATLAB root directory path in the MATLAB installation folder field.
4 Windows OS users also need to click Register MATLAB as COM Server button,

otherwise the specified MATLAB version does not start when calling external
MATLAB functions from the COMSOL model.
5 Click OK.

6 To update the preferences file, close and reopen the COMSOL Desktop.

On Mac OS X, select the COMSOL with MATLAB application available in the

Application folder. The correct path includes the .app extension.

20 |

CHAPTER 2: GETTING STARTED

Calling a MATLAB Function from the

COMSOL Desktop
Use LiveLink for MATLAB to call MATLAB functions from within the model when
working in the COMSOL Desktop. The procedure is slightly different than
implementing a model using a script as you do not need to run COMSOL with
MATLAB.
Start COMSOL Multiphysics as a standalone application. The external MATLAB
function needs to be defined in the COMSOL model so that a MATLAB process can
automatically start when the function needs to be evaluated. The result of the function
evaluation in MATLAB is then sent back to the COMSOL environment.

Calling MATLAB Functions

C A L L I N G A M AT L A B F U N C T I O N F R O M T H E C O M S O L D E S K T O P

21

22 |

CHAPTER 2: GETTING STARTED

Building Models
This chapter gives an overview of the model object and provides an introduction
to building models using the LiveLink interface.
In this chapter:
The Model Object
Working with Geometry
Working with Meshes
Modeling Physics
Creating Selections
Computing the Solution
Analyzing the Results

23

The Model Object

While working with the LiveLink interface in MATLAB you work with models
through the model object. Use methods to create, modify, and access models.
In this section:
Important Notes About the Model Object
The Model Object Methods
The General Utility Functionality
The Model History
Loading and Saving a Model
Sharing the model between the COMSOL Desktop and the MATLAB prompt

Detailed documentation about model object methods is in About

General Commands in the COMSOL API Reference Manual.

Important Notes About the Model Object

Consider the following information regarding the model object:
All algorithms and data structures for the model are integrated in the model object.
The model object is used by the COMSOL Desktop to represent your model. This
means that the model object and the COMSOL Desktop behavior are virtually
identical.
The model object includes methods to set up and run sequences of operations to
create geometry, meshes, and to solve your model.
LiveLink for MATLAB includes the COMSOL API, which is a programming
interface based on Java. In addition, the product includes a number of M-file utility
functions that wrap API functionality for greater ease of use.

The Model Object in the COMSOL API for use with Java Reference
Manual.

24 |

CHAPTER 3: BUILDING MODELS

The Model Object Methods

The model object has a large number of methods. The methods are structured in a
tree-like way, very similar to the nodes in the model tree in the Model Builder window
on the COMSOL Desktop. The top-level methods just return references that support
further methods. At a certain level the methods perform actions, such as adding data
to the model object, performing computations, or returning data.
Detailed documentation about model object methods is in About
General Commands in the COMSOL API for use with Java Reference
Manual.

The links to features described outside of this user guide do not work in
the PDF, only from the online help.

The General Utility Functionality

The model object utility methods are available with the ModelUtil object. These
methods can be used, for example, to create or remove a new model object, but also
to enable the progress bar or list the model object available in the COMSOL server.
MANAGING THE COMSOL MODEL OBJECT

Use the method ModelUtil.create to create a new model object in the COMSOL
server:
model = ModelUtil.create('Model');

This command creates a model object Model on the COMSOL server and a MATLAB
object model that is linked to the model object.
It is possible to have several model objects on the COMSOL server, each with a
different name. To access each model object requires different MATLAB variables
linked to them and each MATLAB variable must have a different name.
Create a MATLAB variable linked to an existing model object with the method
ModelUtil.model. For example, to create a MATLAB variable model that is linked to
the existing model object Model on the COMSOL server, enter the command:
model = ModelUtil.model('Model');

THE MODEL OBJECT

25

To remove a specific model object use the method ModelUtil.remove. For example,
to remove the model object Model from the COMSOL server enter the command:
ModelUtil.remove('Model');

Alternatively remove all the COMSOL objects stored in the COMSOL server with the
command:
ModelUtil.clear

List the names of the model objects available on the COMSOL server with the
command:
list = ModelUtil.tags
ACTIVATING THE PROGRESS BAR

By default no progress information is displayed while running COMSOL with

MATLAB. To manually enable a progress bar and visualize the progress of operations
(such as loading a model, creating a mesh, assembling matrices, or computing the
solution), enter the command:
ModelUtil.showProgress(true);

To deactivate the progress bar enter:

ModelUtil.showProgress(false);

Mac OS X does not support the progress bar.

The Model History

The model contains its entire modeling history corresponding to every settings added
once to the model. When you save a model as an M-file, you get all the operations
performed to the model, including settings that are no longer part of the model.
Using the model history is a convenient way to learn the COMSOL API.
The latest settings enter in the command Desktop being listed at the end
of the M-file.

26 |

CHAPTER 3: BUILDING MODELS

The model history is automatically enabled when the model is created in the
COMSOL Desktop. It is however possible disable manually the model history
recording from the MATLAB prompt with the command:
model.hist.disable;

The function mphload automatically disables model history when loading

a model.
To enable the model history, enter the command:
model.hist.enable;
COMPACTING THE MODEL HISTORY

To clean the M-file for the model so that it contains only the settings that are part of
the current model you need to compact the model history before saving the model as
an M-file.
To compact the model history in the COMSOL Desktop, from File menu (Windows
).
users) or from the toolbar (Mac and Linux users), select Compact History (
To compact the model history at the MATLAB prompt enter the command:
model.resetHist;

Loading and Saving a Model

L O A D I N G A M O D E L A T T H E M AT L A B P RO M P T

To load an existing model saved as an MPH-file use the function mphload. For
example, to load the Busbar model from the COMSOL Multiphysics model library
enter:
model = mphload('busbar.mph');

This creates a model object Model on the COMSOL server that is accessible using the
MATLAB variable model. If there is already a model object Model linked to a
MATLAB variable model, load the model using a different name with the command:
model2 = mphload('busbar.mph','Model2');

When using the function mphload, the model history is automatically disabled to
prevent large history information when running a model in a loop. To turn model
history on, use the function mphload:

THE MODEL OBJECT

27

model = mphload('busbar.mph','-history');

The history recording can be useful when using the COMSOL Desktop.
All the operations are then stored in the saved M-file.

mphload does not look for lock file when loading the model.

SAVING A MODEL

Use the function mphsave to save the model object linked to the MATLAB object
model:
mphsave(model,'filename')

If the filename specified 'filename' does not provide a path, the file is saved relative
to the local MATLAB path. The file extension determines the format to use (*.mph,
*.m, or *.java).
Alternatively, use the save method:
model.save('filename');

If 'filename' does not provide a path, the file is saved relative to the local COMSOL
server path.
Any files saved in the MPH format can be loaded by the COMSOL Desktop. In
addition, the model can be saved as an M-file:
model.save('model_name','m');

The models are not automatically saved between MATLAB sessions.

mphsave does not look for lock file when saving the model.

28 |

CHAPTER 3: BUILDING MODELS

Sharing the model between the COMSOL Desktop and the MATLAB
prompt
It is possible to connect a COMSOL Desktop to the COMSOL server that is already
connected with MATLAB and then access the model from both client (the COMSOL
Desktop and MATLAB). The change performed from either client are directly
accessible from the other one, for instance type a command at the MATLAB prompt
and see the resulting modification in the Model Builder window or extract data at the
MATLAB prompt from a model set up in the COMSOL Desktop.

It is not supported to connect a COMSOL Desktop with a graphics

server.

CONNECT THE COMSOL DESKTOP TO THE COMSOL SER VER

Connect the COMSOL Desktop to a COMSOL server using the Connect to Server
dialog box:
1 From the File (Windows users) or Options menu (Mac and Linux users), select Client
Server>Connect to Server (

).

2 In the Connect to Server window, you specify the server configuration and the user

settings. In the Server section enter the server name (the default name is
localhost) and the Port number (the default is 2036). This number corresponds
to the port that the COMSOL server is listening to, the number is displayed at the
COMSOL server window.
3 In the User section enter a Username and a Password (if they are empty); these are

defined the first time you are connected to the COMSOL server.
4 Click OK.

THE MODEL OBJECT

29

The first time you connect the COMSOL Desktop to the COMSOL
server no model is loaded to the GUI. See Import A Model from the
COMSOL Server to the COMSOL GUI to know how connect the GUI
to a model loaded in the COMSOL server.
IMPOR T A MODEL FROM THE COMSOL SER VER TO THE COMSOL GUI

Once you have the COMSOL Desktop connected to the COMSOL server you can
import the model in the GUI:
1 From the File (Windows users) or Options menu (Mac and Linux users), select Client
Server>Import Model from Server (

).

2 In the Import Model from Server window, specify the model you want to import.
I M P O R T A M O D E L F RO M T H E C O M S O L S E R VE R T O M AT L A B

To access a model stored in the COMSOL server from the MATLAB prompt enter the
command:
model = ModelUtil.model(<ModelName>);

where model is the link in MATLAB to the model stored on the COMSOL server,
<ModelName> the name of the model stored in the COMSOL Model.
You can get the list of the model stored in the COMSOL server with the command:
ModelUtil.tags

Set up a time-out in MATLAB

To prevent MATLAB sending command to the server while it is busy to update the
COMSOL Desktop, you need to set up a time-out in MATLAB and specify how long
to wait the server to be free again. Enter the command:
ModelUtil.setServerBusyHandler(ServerBusyHandler(<time>));

Where <time> is the time in second to wait the server to be free again.

30 |

CHAPTER 3: BUILDING MODELS

Working with Geometry

This section describes how to set up and run a geometry sequence. In this section:
The Geometry Sequence Syntax
Displaying the Geometry
Working with Geometry Sequences
Exchanging Geometries with the COMSOL Desktop
Importing and Exporting Geometries and CAD Models from File
Retrieving Geometry Information
Modeling with a Parameterized Geometry
Images and Interpolation Data
Geometry Modeling and CAD Tools in the COMSOL Multiphysics
Reference Manual
Geometry in the COMSOL API Reference Manual

The links to features described outside of this user guide do not work in
the PDF, only from the online help.

The Geometry Sequence Syntax

In the COMSOL API Reference Manual:
For a list of geometry operations, see About Geometry Commands.
For a property list available for the geometry features see Geometry.
Create a geometry sequence using the syntax:
model.geom.create(<geomtag>, sdim);

where <geomtag> is a string used to refer to the geometry. The integer sdim specifies
the space dimension of the geometry and it can be either 0, 1, 2, or 3.
To add an operation to a geometry sequence, use the syntax:

WO R K I N G W I T H G E O M E T R Y

31

model.geom(<geomtag>).feature.create(<ftag>, operation);

where <geomtag> is the string defined when the geometry is created. The string
<ftag> is used to refer to the operation.
To set the feature property with different values than the default, use the set method:
model.geom(<geomtag>).feature(<ftag>).set(property, <value>);

where <ftag> is the string defined when creating the operation.

To build the geometry sequence, enter:
model.geom(<geomtag>).run;

Alternatively, to build the geometry sequence up to a given feature ftag enter:

model.geom(<geomtag>).run(<ftag>);

Displaying the Geometry

Use the function mphgeom to display the geometry in a MATLAB figure:
mphgeom(model);

To specify the geometry to display, enter:

mphgeom(model, <geomtag>);

When running mphgeom the geometry node is automatically built. Set the build
property to specify how the geometry node is supposed to be built before displaying
it. Enter:
mphgeom(model, <geomtag>, 'build', build);

where build is a string with the value: 'off', 'current', or the geometry feature tag
<ftag>, which, respectively, does not build the geometry (off), builds the geometry
up to the current feature (current), or builds the geometry up to the specified
geometry feature node (ftag).
Use the parent property to specify the axes handle where to display the plot:
mphgeom(model, <geomtag>, 'parent', <axes>);

32 |

CHAPTER 3: BUILDING MODELS

The following properties are also available to specify the vertex, edge, or face
rendering:

edgecolor

facelabelscolor

edgelabels

facemode

edgelabelscolor

vertexlabels

edgemode

vertexlabelscolor

facealpha

vertexmode

facelabels
Use mphgeom to display a specified geometry entity. To set the geometry entity, enter
the entity property and set the geometry entity index in the selection property to:
mphgeom(model, <geomtag>, 'entity', entity, 'selection', <idx>);

where entity can be either 'point', 'edge', 'boundary', or 'domain', and <idx>
is a positive integer array that contains the list of the geometry entity indices.

Working with Geometry Sequences

This section shows how to create geometry sequences using the syntax outlined in The
Geometry Sequence Syntax. This section has these examples:
Creating a 1D Geometry
Creating a 2D Geometry Using Primitive Geometry Objects
Creating a 2D Geometry Using Boundary Modeling
Creating a 3D Geometry Using Solid Modeling

For more information about geometry modeling, see the Geometry

chapter in the COMSOL Multiphysics Reference Manual.

CREATING A 1D GEOMETRY

From the MATLAB command prompt, create a 1D geometry model by adding a

geometry sequence and then adding geometry features. The last step is to run the
sequence using the run method.
First create a model object:

WO R K I N G W I T H G E O M E T R Y

33

model = ModelUtil.create('Model');

Then continue with the commands:

geom1 = model.geom.create('geom1',1);
i1=geom1.feature.create('i1','Interval');
i1.set('intervals','many');
i1.set('p','0,1,2');
geom1.run;

This creates a geometry sequence with a 1D solid object consisting of vertices at x = 0,

1, and 2, and edges joining the vertices adjacent in the coordinate list.
Then enter:
p1=geom1.feature.create('p1','Point');
p1.set('p',0.5);
geom1.run;

to add a point object located at x = 0.5 to the geometry.

To plot the result, enter:
mphgeom(model,'geom1','vertexmode','on')

CREATING A 2D GEOMETR Y USING PRIMITIVE GEOMETR Y OBJECTS

Creating Composite Objects

Use a model object with a 2D geometry. Enter:

34 |

CHAPTER 3: BUILDING MODELS

model = ModelUtil.create('Model');
geom2 = model.geom.create('geom2',2);

Continue by creating a rectangle with side length of 2 and centered at the origin:
sq1 = geom2.feature.create('sq1','Square');
sq1.set('size',2);
sq1.set('base','center');

The property size describes the side lengths of the rectangle and the property pos
describes the positioning. The default is to position the rectangle about its lower left
corner. Use the property base to control the positioning.
Create a circular hole with a radius of 0.5 centered at (0, 0):
c1 = geom2.feature.create('c1','Circle');
c1.set('r',0.5);
c1.set('pos',[0 0]);

The property r describes the radius of the circle, and the property pos describes the
positioning.

The property pos could have been excluded because the default position
is the origin. The default is to position the circle about its center.
Drill a hole in the rectangle by subtracting the circle from it:
co1 = geom2.feature.create('co1','Compose');
co1.selection('input').set({'c1' 'sq1'});
co1.set('formula','sq1-c1');

A selection object is used to refer to the input object. The operators +, *, and correspond to the set operations union, intersection, and difference, respectively.
The Compose operation allows you to work with a formula. Alternatively use the
Difference operation instead of Compose. The following sequence of commands
starts with disabling the Compose operation:
co1.active(false)
dif1 = geom2.feature.create('dif1','Difference');
dif1.selection('input').set({'sq1'});
dif1.selection('input2').set({'c1'});

Run the geometry sequence to create the geometry and plot the result:
geom2.run;

WO R K I N G W I T H G E O M E T R Y

35

mphgeom(model,'geom2');

Trimming Solids
Continue with rounding the corners of the rectangle with the Fillet operation:
fil1 = geom2.feature.create('fil1','Fillet');
fil1.selection('point').set('dif1', [1 2 7 8]);
fil1.set('radius','0.5');

Run the sequence again:

geom2.run;

The geometry sequence is updated with rounded corners. To view the result, enter:
mphgeom(model,'geom2');

36 |

CHAPTER 3: BUILDING MODELS

CREATING A 2D GEOMETRY USING BOUNDARY MODELING

Use the following commands to create six open curve segments that together form a
closed curve:
model = ModelUtil.create('Model');
g1 = model.geom.create('g1',2);
w=1/sqrt(2);
c1 = g1.feature.create('c1','BezierPolygon');
c1.set('type','open');
c1.set('degree',2);
c1.set('p',[-0.5 -1 -1;-0.5 -0.5 0]);
c1.set('w',[1 w 1]);
c2 = g1.feature.create('c2','BezierPolygon');
c2.set('type','open');
c2.set('degree',2);
c2.set('p',[-1 -1 -0.5;0 0.5 0.5]);
c2.set('w',[1 w 1]);
c3 = g1.feature.create('c3','BezierPolygon');
c3.set('type','open');
c3.set('degree',1);
c3.set('p',[-0.5 0.5; 0.5 0.5]);
c4 = g1.feature.create('c4','BezierPolygon');
c4.set('type','open');
c4.set('degree',2);

WO R K I N G W I T H G E O M E T R Y

37

c4.set('p',[0.5 1 1; 0.5 0.5 0]);

c4.set('w',[1 w 1]);
c5 = g1.feature.create('c5','BezierPolygon');
c5.set('type','open');
c5.set('degree',2);
c5.set('p',[1 1 0.5; 0 -0.5 -0.5]);
c5.set('w',[1 w 1]);
c6 = g1.feature.create('c6','BezierPolygon');
c6.set('type','open');
c6.set('degree',1);
c6.set('p',[0.5 -0.5; -0.5 -0.5]);

The objects c1, c2, c3, c4, c5, and c6 are all curve2 objects. The vector [1 w 1]
specifies the weights for a rational Bzier curve that is equivalent to a quarter-circle arc.
The weights can be adjusted to create elliptical or circular arcs.
Convert the curve segments to a solid with the following conversion command:
csol1 = g1.feature.create('csol1','ConvertToSolid');
csol1.selection('input').set({'c1' 'c2' 'c3' 'c4' 'c5' 'c6'});

Then issue a final run command:

g1.run;
mphgeom(model,'g1');

CREATING A 3D GEOMETRY USING SOLID MODELING

This section shows how to create 3D solids using workplanes and Boolean operations.
Create a 3D geometry with an xy work plane at z = 0:

38 |

CHAPTER 3: BUILDING MODELS

model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1', 3);
wp1 = geom1.feature.create('wp1', 'WorkPlane');
wp1.set('planetype', 'quick');
wp1.set('quickplane', 'xy');

Add a rectangle to the work plane, then add fillet to its corners:
r1 = wp1.geom.feature.create('r1', 'Rectangle');
r1.set('size',[1 2]);
geom1.run
fil1 = wp1.geom.feature.create('fil1', 'Fillet');
fil1.selection('point').set('r1', [1 2 3 4]);
fil1.set('radius', '0.125');
geom1.runCurrent;
ext1 = geom1.feature.create('ext1', 'Extrude');
ext1.set('distance', '0.1');

Add another yz work plane, at x = 0.5:

wp2 = geom1.feature.create('wp2', 'WorkPlane');
wp2.set('planetype', 'quick');
wp2.set('quickplane', 'yz');
wp2.set('quickx', '0.5');
b1 = wp2.geom.feature.create('b1', 'BezierPolygon');
b1.set('type', 'open');
b1.set('degree', [1 1 1 1]);
b1.set('p',
{'0.75','1','1','0.8','0.75';'0.1','0.1','0.05','0.05','0.1'});
b1.set('w', {'1','1','1','1','1','1','1','1'});
wp2.geom.feature.create('csol1', 'ConvertToSolid');
wp2.geom.feature('csol1').selection('input').set({'b1'});

Revolve the triangle from the yz work plane:

rev1 = geom1.feature.create('rev1', 'Revolve');
rev1.selection('input').set({'wp2'});
rev1.setIndex('pos', '1', 0);

Add the difference operation that computes the final 3D geometry:

dif1 = geom1.feature.create('dif1', 'Difference');
dif1.selection('input').set({'ext1'});
dif1.selection('input2').set({'rev1'});

WO R K I N G W I T H G E O M E T R Y

39

To run the sequence, enter:

geom1.run;

To view the geometry enter:

mphgeom(model);

Exchanging Geometries with the COMSOL Desktop

To transfer a geometry from the COMSOL Desktop to the LiveLink interface in
MATLAB, use one of these methods.

Export the Geometry from the COMSOL Desktop

Export the geometry as a COMSOL Multiphysics binary (.mphbin) file from the
COMSOL Desktop. Right-click the Geometry node and select Export to File. Then
create a geometry import feature from MATLAB:
model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1', 3);
imp1 = geom1.feature.create('imp1','Import');
imp1.set('filename','geometryfile.mphbin');
imp1.importData;
geom1.run;

40 |

CHAPTER 3: BUILDING MODELS

Save the Geometry

Save the model containing the geometry sequence from the COMSOL Desktop.
Create a model object from MATLAB and load the file into it.

Export the Model to the COMSOL Server

Export the model containing the geometry sequence to the COMSOL server.

Importing and Exporting Geometries and CAD Models from File

With COMSOL Multiphysics, you can import and export geometries in a variety of file
formats.
COMSOL MULTIPHYSICS FILES

A natural choice for storing geometries in 1D, 2D, and 3D is the native file format of
COMSOLs geometry kernel (.mphtxt and .mphbin).

The .mphtxt or .mphbin file formats are only used for geometry and
mesh objects. It is not the same as a Model MPH-file (.mph).

2D CAD FORMATS

COMSOL Multiphysics supports import and export for the DXF file format, a data
interchange format of the CAD system AutoCAD . Files can also be imported using
the neutral GDS format. The ECAD geometry file format requires either the AC/DC
Module, MEMS Module, or the RF Module.
See the ECAD Import Module Users Guide or go to
http://www.comsol.com/comsol-multiphysics/ for more information
about this and other products.
3D CAD FORMATS

It is possible to import surface meshes in the STL and VRML formats. With a license
for the CAD Import Module, or one of the LiveLink for CAD products, you can
import most 3D CAD file formats: Parasolid, ACIS (SAT), STEP, IGES,
Pro/ENGINEER, Autodesk Inventor, and SolidWorks . See the specific product
documentation for detailed information.

WO R K I N G W I T H G E O M E T R Y

41

Retrieving Geometry Information

To retrieve the detailed information about the geometry in a model, see
Geometry Object Information Methods in the COMSOL API Reference
Manual.
First create a simple 3D geometry:
model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1', 3);
geom1.feature.create('blk1','Block');
geom1.feature.create('con1','Cone');
geom1.run;

To visualize the geometry in a MATLAB figure window enter:

mphgeom(model)

The model object contains general geometry information methods. For example, to
determine the space dimension of the geometry, enter:
geom1.getSDim

There are also methods to determine the number of geometrical entities. For example,
to inquire about the number of domains and the number of boundaries:
geom1.getNDomains
geom1.getNBoundaries

42 |

CHAPTER 3: BUILDING MODELS

Another group of geometry information methods concern adjacency properties of the

geometric entities. For example, the number of up and down domain information on
each boundary:
geom1.getUpDown

There are also methods for evaluating properties such as coordinate values and
curvatures on faces and edges. For example, to evaluate coordinates on face 1 for the
face parameters (2, 0.005), enter:
geom1.faceX(1,[2,0.005])

To get the parameters of a given face, use the method faceParamRange(N), where N
is the face number. For example:
geom1.faceParamRange(1)

returns the parameters for face 1.

To get the parameter range of an edge, use the edgeParamRange(N) method. For
example, to get the length of edge number 3, enter:
geom1.edgeParamRange(3)

To get the coordinate and the curvature data along a specified edge, enter:
geom1.edgeX(2,0.5)
geom1.edgeCurvature(2,0.5)

There are also methods for getting information about the internal representation of
the geometry. For example, the coordinates of the geometry vertices:
geom1.getVertexCoord

To fetch geometry information from elements in the geometry sequence, enter:

geom1.obj('blk1').getNBoundaries

Modeling with a Parameterized Geometry

COMSOL Multiphysics has built-in support for parameterized geometries. Parameters
can be used in most geometry operations. To exemplify parameterizing a geometry,
the following script studies the movement of a circular source through two adjacent
rectangular domains:
model = ModelUtil.create('Model');
model.param.set('a','0.2');
geom1 = model.geom.create('geom1',2);

WO R K I N G W I T H G E O M E T R Y

43

r1 = geom1.feature.create('r1','Rectangle');
r1.set('size',[0.5 1]);
r1.set('pos',[0 0]);
r2 = geom1.feature.create('r2','Rectangle');
r2.set('size',[0.6 1]);
r2.set('pos',[0.5 0]);
c1 = geom1.feature.create('c1','Circle');
c1.set('r',0.1);
c1.set('pos',{'a','0.5'});
mphgeom(model);

Change the position of the circle by changing the value of parameter a:

model.param.set('a','0.5');
mphgeom(model);

44 |

CHAPTER 3: BUILDING MODELS

Create a loop that changes the position of the circle in increments:

for a=0.2:0.1:0.5
model.param.set('a',a);
geom1.run;
end

Create a mesh:
model.mesh.create('mesh1', 'geom1');

Add a Weak Form PDE interface:

w = model.physics.create('w', 'WeakFormPDE', 'geom1');
w.feature('wfeq1').set('weak', 1, '-test(ux)*ux-test(uy)*uy');
dir1 = w.feature.create('dir1', 'DirichletBoundary', 1);
dir1.selection.set([1 2 3 6 7]);
src1 = w.feature.create('src1', 'SourceTerm', 2);
src1.set('f', 1, '1');
src1.selection.set([3]);

Then, create a stationary study step:

std1 = model.study.create('std1');
stat1 = std1.feature.create('stat1', 'Stationary');

Create a parametric sweep feature:

p1 = model.batch.create('p1','Parametric');
p1.set('pname', 'a');
p1.set('plist','range(0.2,0.1,0.8)');

WO R K I N G W I T H G E O M E T R Y

45

p1.run;

Alternatively, you can run the parametric sweep using a MATLAB for loop:
for a=0.2:0.1:0.8
model.param.set('a',a);
std1.run;
end

After updating a parameter that affects the geometry, COMSOL detects

this change and automatically updates the geometry and mesh before
starting the solver. The geometry is associative, which means that physics
settings are preserved as the geometry changes.

Images and Interpolation Data

This section describes how to generate geometry from a set of data points by using
interpolation curves and how to create geometry from image data.
Creating a Geometry Using Curve Interpolation
Creating Geometry from Image Data
CREATING A GEOMETRY USING CUR VE INTERPOLATION

Use the interpolation spline feature to import a set of data points that describe a 2D
geometry. To create an interpolation spline feature, enter:
model.geom(<geomtag>).feature.create(<ftag>,'InterpolationCurve')

Then specify data points in a table:

model.geom(<geomtag>).feature(<ftag>).set('table',<data>)

where <data> can either be a 2xN cell array or a 2xN array.

Control the type of geometry generated by the operation with the command:
model.geom(<geomtag>).feature(<ftag>).set('type',type)

where type can either be 'solid' to generate a solid object, 'closed' to generate a
closed curve or 'open' to generate an open curve.

Example: Curve Interpolation

Create a set of data points in MATLAB, then use these to construct a 2D geometry.
1 Create data points that describe a circle, sorted by the angle, and remove some of

the points:

46 |

CHAPTER 3: BUILDING MODELS

phi = 0:0.2:2*pi;
phi([1 3 6 7 10 20 21 25 28 32]) = [];
p = [cos(phi);sin(phi)];

2 Add some noise to the data points:

randn('state',17)
p = p+0.02*randn(size(p));

3 Create a 2D geometry with a square:

model = ModelUtil.create('Model');

4 Add a square geometry:

geom1 = model.geom.create('geom1', 2);
sq1 = geom1.feature.create('sq1', 'Square');
sq1.set('base', 'center');
sq1.set('size', '3');

5 Add an interpolation curve feature:

ic1 = geom1.feature.create('ic1', 'InterpolationCurve');

6 Use the variable p for the data points:

ic1.set('table', p');

7 Specify a closed curve:

ic1.set('type', 'closed');

8 Plot the geometry with the mphgeom command:

mphgeom(model);

WO R K I N G W I T H G E O M E T R Y

47

CREATING GEOMETRY FROM IMAGE DATA

Use the function mphimage2geom to create geometry from image data. The image data
format can be M-by-N array for a grayscale image or M-by-N-by-3 array for a true
color image. This section also includes an example (see Example: Convert Image Data
to Geometry).

See the MATLAB function imread to convert an image file to image data.

If you specify the image data and the level value that represents the geometry contour
you want to extract, the function mphimage2geom returns a model object with the
desired geometry:
model = mphimage2geom(<imagedata>, <level>)

where imagedata is a C array containing the image data and level is the contour level
value used to generate the geometry contour.
Specify the type of geometry object generated:
model = mphimage2geom(<imagedata>, <level>, 'type', type)

where type is 'solid' and generates a solid object, 'closed' generates a closed
curve object, or 'open' generates an open curve geometry object.
Use the property curvetype to specify the type of curve used to generate the
geometry object:
model = mphimage2geom(<imagedata>, <level>, 'curvetype', curvetype)

where curvetype can be set to 'polygon' to use a polygon curve. The default curve
type creates a geometry with the best suited geometrical primitives. For interior curves
it uses interpolation curves, while for curves that are touching the perimeter of the
image a polygon curve is used.
To scale the geometry use the scale property where scale is a double value:
model = mphimage2geom(<imagedata>, <level>, 'scale', scale)

Set the minimum distance between coordinates in curve with the mindist property
where mindist is a double value:
model = mphimage2geom(<imagedata>, <level>, 'mindist', mindist)

Set the minimum area for interior curves where minarea is a double value:

48 |

CHAPTER 3: BUILDING MODELS

model = mphimage2geom(<imagedata>, <level>, 'minarea', minarea)

In case of overlapping solids, the function mphimage2geom automatically creates a

Compose node in the model object. If you do not want this geometry feature, set the
property compose to off:
model = mphimage2geom(<imagedata>, <level>, 'compose', 'off')

To create a rectangle domain surrounding the object generated use the property
rectangle:
model = mphimage2geom(<imagedata>, <level>, 'rectangle', 'on')

Example: Convert Image Data to Geometry

This example shows how to create geometry based on gray scale image data. First
generate the image data in MATLAB and display the contour in a figure. Then, create
a model object including the geometry represented by the contour value 40.
At the MATLAB prompt enter these commands:
p = (peaks+7)*5;
[c,h] = contourf(p);
clabel(c, h);
model = mphimage2geom(p, 40);
figure(2)
mphgeom(model)

Use the property type to create closed or open curves. For example, to create a
geometry following contour 40 with closed curves, enter:
model = mphimage2geom(p, 40, 'type', 'closed');

WO R K I N G W I T H G E O M E T R Y

49

mphgeom(model)

To scale the geometry, use the scale property. Using the current model scale the
geometry with a factor of 0.001 (1e-3):
model = mphimage2geom(p, 40, 'scale', 1e-3);
mphgeom(model)

To insert a rectangle in the geometry that has an outer domain surrounding the
created contour, set the property rectangle to on:
model = mphimage2geom(p, 40, 'rectangle', 'on');
mphgeom(model)

50 |

CHAPTER 3: BUILDING MODELS

WO R K I N G W I T H G E O M E T R Y

51

Working with Meshes

This section describes how to set up and run meshing sequences in a model.
The Meshing Sequence Syntax
Displaying the Mesh
Mesh Creation Functions
Importing External Meshes and Mesh Objects
Measuring Mesh Quality
Getting Mesh Statistics Information
Getting and Setting Mesh Data

Meshing in the COMSOL Multiphysics Reference Manual

Mesh in the COMSOL API Reference Manual

The links to features described outside of this user guide do not work in
the PDF, only from the online help.

The Meshing Sequence Syntax

Create a meshing sequence by using the syntax:
model.mesh.create(<meshtag>, <geomtag>);

where <meshtag> is a string that you use to refer to the sequence. The tag geomtag
specifies the geometry to use for this mesh node.
To add an operation to a sequence, use the syntax:
model.mesh(<meshtag>).feature.create(<ftag>, operation);

where the string <ftag> is a string that you use to refer to the operation.

About Mesh Commands in the COMSOL API Reference Manual

52 |

CHAPTER 3: BUILDING MODELS

To set a property to a value in a operation, enter:

model.mesh(<meshtag>).feature(<ftag>).set(property, <value>);

To build the mesh sequence, enter:

model.mesh(<meshtag>).run;

To run the mesh node up to a specified feature node <ftag>, enter:

model.mesh(<meshtag>).run(ftag);

For more details on available operations and properties in the sequence,

see Mesh in the COMSOL API Reference Manual.

Displaying the Mesh

To display the mesh in a MATLAB figure, use the function mphmesh. Make sure that
the mesh is built before calling this command:
mphmesh(model);

If there are several meshes in a model, specify the mesh to display using the command:
mphmesh(model, <meshtag>);

Use the parent property to specify the axes handle where to display the plot:
mphmesh(model, <meshtag>, 'parent', <axes>);

The following properties are also available to specify the vertex, edge, or face
rendering:

edgecolor

facelabelscolor

edgelabels

facemode

edgelabelscolor

meshcolor

edgemode

vertexlabels

facealpha

vertexlabelscolor

facelabels

vertexmode

WO R K I N G W I T H M E S H E S

53

Mesh Creation Functions

Several mesh features are discussed, with examples in this section:
Mesh Sizing Properties
Creating Structured Meshes
Building a Mesh Incrementally
Revolving a Mesh by Sweeping
Extruding a Mesh by Sweeping
Combining Unstructured and Structured Meshes
Creating Boundary Layer Meshes
Refining Meshes
Copying Boundary Meshes
Converting Mesh Elements
MESH SIZING PROPERTIES

The Size attribute provides a number of input properties that can control the mesh
element size, such as the following properties:
Maximum and minimum element size
Element growth rate
Curvature factor
Resolution of narrow regions
These properties are available both globally and locally. The following examples are
included: Example: Creating a 2D Mesh with Triangular Elements and Example:
Creating a 2D Mesh with Quadrilateral Elements. Also discussed is The Free Meshing
Method.

54 |

CHAPTER 3: BUILDING MODELS

There are several predefined settings that can be used to set a suitable combination of
values for many properties. To select one of these settings, use the property hauto and
pass an integer from 1 to 9 as its value to describe the mesh resolution:
Extremely fine (1)

Coarse (6)

Extra fine (2)

Coarser (7)

Finer (3)

Extra coarse (8)

Fine (4)

Extremely coarse (9)

Normal (5) (the default)

For details about predefined mesh size settings and mesh element size
parameters, see Size in the COMSOL API Reference Manual.

Example: Creating a 2D Mesh with Triangular Elements

Generate a triangular mesh of a unit square:
model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1',2);
geom1.feature.create('r1','Rectangle');
mesh1 = model.mesh.create('mesh1','geom1');
ftri1 = mesh1.feature.create('ftri1','FreeTri');
mesh1.run;
mphmesh(model);

WO R K I N G W I T H M E S H E S

55

Figure 3-1: Default mesh on a unit square.

The default size feature is generated with the property hauto set to 5, that is:
mesh1.feature('size').set('hauto','5');

To override this behavior, set hauto to another integer. Override this by setting
specific size properties, for example, making the mesh finer than the default by
specifying a maximum element size of 0.02:
mesh1.feature('size').set('hmax','0.02');
mesh1.run;
mphmesh(model);

56 |

CHAPTER 3: BUILDING MODELS

This value corresponds to 1/50 of the largest axis-parallel distance, whereas the default
value is 1/15.

Figure 3-2: Fine mesh (maximum element size = 0.02).

Sometimes a nonuniform mesh is desirable. Make a mesh that is denser on the left side
by specifying a smaller maximum element size only on the edge segment to the left
(edge number 1):
mesh1.feature('size').set('hauto','5');
size1 = ftri1.feature.create('size1','Size');
size1.set('hmax','0.02');
size1.selection.geom('geom1',1);
size1.selection.set(1);
mesh1.run
mphmesh(model);

WO R K I N G W I T H M E S H E S

57

Figure 3-3: Nonuniform mesh.

The Free Meshing Method

The default method to generate free triangle meshes in 2D is based on an advancing
front algorithm. To switch to a Delaunay algorithm use the value del for the method
property. Start by creating a geometry:
model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1',2);
geom1.feature.create('r1','Rectangle');
c1 = geom1.feature.create('c1','Circle');
c1.set('r','0.5');
co1=geom1.feature.create('co1','Compose');
co1.selection('input').set({'c1' 'r1'});
co1.set('formula','r1-c1');
geom1.runAll;
mesh1 = model.mesh.create('mesh1','geom1');
ftri1 = mesh1.feature.create('ftri1','FreeTri');
ftri1.set('method','del');
mesh1.run;
mphmesh(model,'mesh1')

58 |

CHAPTER 3: BUILDING MODELS

Figure 3-4: Mesh created with the Delaunay method.

Example: Creating a 2D Mesh with Quadrilateral Elements

To create an unstructured quadrilateral mesh on a unit circle, enter:
model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1',2);
geom1.feature.create('c1','Circle');
mesh1 = model.mesh.create('mesh1','geom1');
mesh1.feature.create('ftri1','FreeQuad');
mesh1.run;
mphmesh(model)

WO R K I N G W I T H M E S H E S

59

Figure 3-5: Free quad mesh.

CREATING STRUCTURED MESHES

To create a structured quadrilateral mesh in 2D, use the Map operation. This operation
uses a mapping technique to create the quadrilateral mesh.

Map in the COMSOL API Reference Manual

Use the EdgeGroup attribute to group the edges (boundaries) into four edge groups,
one for each edge of the logical mesh. To control the edge element distribution use
the Distribution attribute, which determines the overall mesh density.

Example: Creating a Structured Quadrilateral Mesh

Create a structured quadrilateral mesh on a geometry where the domains are bounded
by more than four edges:
model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1',2);
geom1.feature.create('r1','Rectangle');
r2 = geom1.feature.create('r2','Rectangle');
r2.set('pos',[1 0]);
c1 = geom1.feature.create('c1','Circle');
c1.set('r','0.5');
c1.set('pos',[1.1 -0.1]);
dif1 = geom1.feature.create('dif1', 'Difference');
dif1.selection('input').set({'r1' 'r2'});

60 |

CHAPTER 3: BUILDING MODELS

dif1.selection('input2').set({'c1'});
geom1.run('dif1');
mesh1 = model.mesh.create('mesh1','geom1');
map1 = mesh1.feature.create('map1','Map');
eg1 = map1.feature.create('eg1', 'EdgeGroup');
eg1.selection.set(1);
eg1.selection('edge1').set([1 3]);
eg1.selection('edge2').set(2);
eg1.selection('edge3').set(8);
eg1.selection('edge4').set(4);
eg2 = map1.feature.create('eg2', 'EdgeGroup');
eg2.selection.set(2);
eg2.selection('edge1').set(4);
eg2.selection('edge2').set([6 9 10]);
eg2.selection('edge3').set(7);
eg2.selection('edge4').set(5);
mesh1.run;
mphmesh(model);

Figure 3-6: Structured quadrilateral mesh (right) and its underlying geometry.
The left-hand side plot in Figure 3-6 is obtained with this command:
mphgeom(model, 'geom1', 'edgelabels','on')

The EdgeGroup attributes specify that the four edges enclosing domain 1 are
boundaries 1 and 3; boundary 2; boundary 8; and boundary 4. For domain 2 the four
edges are boundary 4; boundary 5; boundary 7; and boundaries 9, 10, and 6.

WO R K I N G W I T H M E S H E S

61

BUILDING A MESH INCREMENTALLY

To build meshes in a step-by-step fashion, create selections for the parts of the
geometry that you want to mesh in each step, as in this example:
model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1',2);
geom1.feature.create('r1','Rectangle');
geom1.feature.create('c1','Circle');
uni1 = geom1.feature.create('uni1', 'Union');
uni1.selection('input').set({'c1' 'r1'});
geom1.runCurrent;
del1 = geom1.feature.create('del1', 'Delete');
del1.selection('input').init(1);
del1.selection('input').set('uni1', 8);
geom1.run('del1');
mesh1 = model.mesh.create('mesh1','geom1');
dis1 = mesh1.feature.create('dis1', 'Distribution');
dis1.selection.set([2 4]);
dis1.set('type', 'predefined');
dis1.set('method', 'geometric');
dis1.set('elemcount', '20');
dis1.set('reverse', 'on');
dis1.set('elemratio', '20');
dis2 = mesh1.feature.create('dis2', 'Distribution');
dis2.selection.set([1 3]);
dis2.set('type', 'predefined');
dis2.set('method', 'geometric');
dis2.set('elemcount', '20');
dis2.set('elemratio', '20');
map1 = mesh1.feature.create('map1','Map');
map1.selection.geom('geom1', 2);
map1.selection.set(2);
mesh1.feature.create('frt1','FreeTri');
mesh1.run;
mphmesh(model);

62 |

CHAPTER 3: BUILDING MODELS

The final mesh is in Figure 3-7. Note the effect of the Distribution feature, with
which the distribution of vertex elements along geometry edges can be controlled.

Figure 3-7: Incrementally generated mesh (right).

The left-hand side plot in Figure 3-7 is obtained with this command:
mphgeom(model, 'geom1', 'edgelabels','on')

To replace the structured quad mesh by an unstructured quad mesh, delete the Map
feature and replace it by a FreeQuad feature:
mesh1.feature.remove('map1');
mesh1.run('dis1');
fq1 = mesh1.feature.create('fq1', 'FreeQuad');
fq1.selection.geom('geom1', 2).set(2);
mesh1.run;

Analogous to working with the meshing sequence in the Model Builder

in the COMSOL Desktop, new features are always inserted after the
current feature.
Thus, to get the FreeQuad feature before the FreeTri feature, the dis1 feature needs
to be made the current feature by building it with the run method. Alternatively, parts
of a mesh can be selectively removed by using the Delete feature. For example, to
remove the structured mesh from domain 2 (along with the adjacent edge mesh on
edges 3 and 4), and replace it with an unstructured quad mesh, enter these commands:
del1 = mesh1.feature.create('del1','Delete');
del1.selection.geom('geom1', 2).set(2);
del1.set('deladj','on');
frq1 = mesh1.feature.create('frq1','FreeQuad');
frq1.selection.geom('geom1', 2).set(2);
mesh1.run;

WO R K I N G W I T H M E S H E S

63

For further details on the various commands and their properties see the
COMSOL API Reference Manual.

REVO LVING A MES H BY SWEEPING

Create 3D volume meshes by extruding and revolving face meshes with the Sweep
feature. Depending on the 2D mesh type, the 3D meshes can be hexahedral (brick)
meshes or prism meshes.

Example: Revolved Mesh

Create and visualize a revolved prism mesh as follows:
model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1', 3);
wp1 = geom1.feature.create('wp1', 'WorkPlane');
wp1.set('planetype', 'quick');
wp1.set('quickplane', 'xy');
c1 = wp1.geom.feature.create('c1', 'Circle');
c1.set('pos', [2, 0]);
rev1 = geom1.feature.create('rev1', 'Revolve');
rev1.set('angle2', '60').set('angle1', '-60');
rev1.selection('input').set({'wp1'});
geom1.run('rev1');
mesh1 = model.mesh.create('mesh1', 'geom1');
mesh1.feature.create('ftri1', 'FreeTri');
mesh1.feature('ftri1').selection.geom(2);
mesh1.feature('ftri1').selection.set(2);
mesh1.runCurrent;
swe1 = mesh1.feature.create('swe1', 'Sweep');
swe1.selection.geom(3);
swe1.selection.add(1);
mesh1.run;
mphmesh(model)

To obtain a torus, leave the angles property unspecified; the default value gives a
complete revolution.

64 |

CHAPTER 3: BUILDING MODELS

Figure 3-8: 3D prism mesh created with the Sweep feature.

EXTRUDING A MESH BY SWEEPING

To generate a 3D prism mesh from the same 2D mesh by extrusion and then to plot
it, enter these commands:
model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1', 3);
wp1 = geom1.feature.create('wp1', 'WorkPlane');
wp1.set('planetype', 'quick');
wp1.set('quickplane', 'xy');
c1 = wp1.geom.feature.create('c1', 'Circle');
c1.set('pos', [2, 0]);
ext1 = geom1.feature.create('ext1', 'Extrude');
ext1.selection('input').set({'wp1'});
geom1.runAll;
mesh1 = model.mesh.create('mesh1', 'geom1');
ftri1 = mesh1.feature.create('ftri1', 'FreeTri');
ftri1.selection.geom('geom1', 2);
ftri1.selection.set(3);
dis1 = mesh1.feature.create('dis1', 'Distribution');
dis1.selection.set(1);
dis1.set('type', 'predefined');
dis1.set('elemcount', '20');
dis1.set('elemratio', '100');
swe1 = mesh1.feature.create('swe1', 'Sweep');
swe1.selection('sourceface').geom('geom1', 2);

WO R K I N G W I T H M E S H E S

65

swe1.selection('targetface').geom('geom1', 2);
mesh1.run;
mphmesh(model);

The result is shown in Figure 3-9. With the properties elemcount and elemratio the
number and distribution of mesh element layers is controlled in the extruded direction.

Distribution in the COMSOL API Reference Manual

Figure 3-9: Extruded 3D prism mesh.

COMBINING UNSTRUCTURED AND STRUCTURED MESHES

By specifying selections for the meshing operations, swept meshing can also be
combined with free meshing. In this case, start by free meshing domain 2, then sweep
the resulting surface mesh through domain 1, as in this example:
model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1', 3);
cone1 = geom1.feature.create('cone1', 'Cone');
cone1.set('r', '0.3');
cone1.set('h', '1');
cone1.set('ang', '9');
cone1.set('pos', [ 0 0.5 0.5]);
cone1.set('axis', [-1 0 0]);
geom1.feature.create('blk1', 'Block');

66 |

CHAPTER 3: BUILDING MODELS

mesh1 = model.mesh.create('mesh1', 'geom1');

ftet1 = mesh1.feature.create('ftet1', 'FreeTet');
ftet1.selection.geom('geom1', 3);
ftet1.selection.set(2);
swe1 = mesh1.feature.create('swe1', 'Sweep');
swe1.selection('sourceface').geom('geom1', 2);
swe1.selection('targetface').geom('geom1', 2);
mesh1.run;
mphmesh(model);

Figure 3-10: Combined structured/unstructured mesh.

The left-hand side plot in Figure 3-10 is obtained with this command:
mphgeom(model,'geom1','facemode','off','facelabels','on')
CREATING BOUNDARY LAYER MESHES

For 2D and 3D geometries it is also possible to create boundary layer meshes using the
BndLayer feature. A boundary layer mesh is a mesh with dense element distribution
in the normal direction along specific boundaries. This type of mesh is typically used
for fluid flow problems to resolve the thin boundary layers along the no-slip
boundaries. In 2D, a layered quadrilateral mesh is used along the specified no-slip
boundaries. In 3D, a layered prism mesh or hexahedral mesh is used depending on
whether the corresponding boundary layer boundaries contain a triangular or a
quadrilateral mesh.
If starting with an empty mesh, the boundary-layer mesh uses free meshing to create
the initial mesh before inserting boundary layers into the mesh. This generates a mesh

WO R K I N G W I T H M E S H E S

67

with triangular and quadrilateral elements in 2D and tetrahedral and prism elements in
3D. The following example illustrates this in 2D:
model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1', 2);
r1 = geom1.feature.create('r1', 'Rectangle');
r1.set('size', [10, 5]);
c1 = geom1.feature.create('c1', 'Circle');
c1.set('pos', [3.5 2.5]);
dif1 = geom1.feature.create('dif1', 'Difference');
dif1.selection('input').set({'r1'});
dif1.selection('input2').set({'c1'});
geom1.runAll;
mesh1 = model.mesh.create('mesh1', 'geom1');
bl1 = mesh1.feature.create('bl1', 'BndLayer');
bl1.feature.create('blp1', 'BndLayerProp');
bl1.feature('blp1').selection.set([2 3 5 6 7 8]);
mesh1.run;
mphmesh(model);

Figure 3-11: Boundary layer mesh based on an unstructured triangular mesh.

It is also possible to insert boundary layers in an existing mesh. Use the following
meshing sequence with the geometry sequence from the previous example:
bl1.active(false);
fq1 = mesh1.feature.create('fq1', 'FreeQuad');

68 |

CHAPTER 3: BUILDING MODELS

fq1.selection.set([1]);
mphmesh(model)
bl1 = mesh1.feature.create('bl2', 'BndLayer');
bl1.feature.create('blp2', 'BndLayerProp');
bl1.feature('blp2').selection.set([2 3 5 6 7 8]);
mesh1.run;
mphmesh(model);

Figure 3-12: Initial unstructured quad mesh (left) and resulting boundary layer mesh
(right).
REFINING MESHES

Given a mesh consisting only of simplex elements (lines, triangles, and tetrahedra) you
can create a finer mesh using the feature Refine. Enter this command to refine the
mesh:
mesh1.feature.create('ref1', 'Refine');

By specifying the property tri, either as a row vector of element numbers or a 2-row
matrix, the elements to be refined can be controlled. In the latter case, the second row
of the matrix specifies the number of refinements for the corresponding element.
The refinement method is controlled by the property rmethod. In 2D, its default value
is regular, corresponding to regular refinement, in which each specified triangular
element is divided into four triangles of the same shape. Setting rmethod to longest
gives longest edge refinement, where the longest edge of a triangle is bisected. Some
triangles outside the specified set might also be refined in order to preserve the
triangulation and its quality.

WO R K I N G W I T H M E S H E S

69

In 3D, the default refinement method is longest, while regular refinement is only
implemented for uniform refinements. In 1D, the function always uses regular
refinement, where each element is divided into two elements of the same shape.
For stationary or eigenvalue PDE problems you can use adaptive mesh
refinement at the solver stage with the solver step adaption. See
Adaption in the COMSOL API Reference Manual.
COPYING BOUNDAR Y MESHES

Use the CopyEdge feature in 2D and the CopyFace feature in 3D to copy a mesh
between boundaries.

It is only possible to copy meshes between boundaries that have the same
shape. However, a scaling factor between the boundaries is allowed.
The following example demonstrates how to copy a mesh between two boundaries in
3D and then create a swept mesh on the domain:
model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1', 3);
wp1 = geom1.feature.create('wp1', 'WorkPlane');
wp1.set('planetype', 'quick');
wp1.set('quickplane', 'xy');
c1 = wp1.geom.feature.create('c1', 'Circle');
c1.set('r', 0.5);
c1.set('pos', [1, 0]);
rev1 = geom1.feature.create('rev1', 'Revolve');
rev1.set('angle1', '0').set('angle2', '180');
rev1.selection('input').set({'wp1'});
geom1.run('wp1');
mesh1 = model.mesh.create('mesh1', 'geom1');
size1 = mesh1.feature.create('size1', 'Size');
size1.selection.geom('geom1', 1);
size1.selection.set(18);
size1.set('hmax', '0.06');
ftri1 = mesh1.feature.create('ftri1', 'FreeTri');
ftri1.selection.geom('geom1', 2);
ftri1.selection.set(10);

70 |

CHAPTER 3: BUILDING MODELS

cpf1 = mesh1.feature.create('cpf1', 'CopyFace');

cpf1.selection('source').geom('geom1', 2);
cpf1.selection('destination').geom('geom1', 2);
cpf1.selection('source').set(10);
cpf1.selection('destination').set(1);
sw1 = mesh1.feature.create('sw1', 'Sweep');
sw1.selection('sourceface').geom('geom1', 2);
sw1.selection('targetface').geom('geom1', 2);
mesh1.run;
mphmesh(model);

The algorithm automatically determines how to orient the source mesh on the target
boundary. The result is shown in Figure 3-13.

Figure 3-13: Prism element obtained with the CopyFace and Sweep features.
To explicitly control the orientation of the copied mesh, use the EdgeMap attribute.
The command sequence:
em1 = cpf1.feature.create('em1', 'EdgeMap');
em1.selection('srcedge').set(18);
em1.selection('dstedge').set(2);
mesh1.feature.remove('sw1');
mesh1.feature.create('ftet1', 'FreeTet');
mesh1.run;
mphmesh(model);

copies the mesh between the same boundaries as in the previous example, but now the
orientation of the source mesh on the target boundary is different. The domain is then

WO R K I N G W I T H M E S H E S

71

meshed by the free mesh, resulting in the mesh in Figure 3-14. In this case it is not
possible to create a swept mesh on the domain because the boundary meshes do not
match in the sweeping direction.

Figure 3-14: Free tetrahedral mesh after the use of the CopyFace feature.
CONVERTING MESH ELEMENTS

Use the Convert feature to convert meshes containing quadrilateral, hexahedral, or

prism elements into triangular meshes and tetrahedral meshes. In 2D, the function
splits each quadrilateral element into either two or four triangles. In 3D, it converts
each prism into three tetrahedral elements and each hexahedral element into five, six,
or 28 tetrahedral elements. To control the method used to convert the elements, use
the property splitmethod. The default value is diagonal, which results in two
triangular elements in 2D and five or six tetrahedral elements in 3D.

For additional properties supported, see Convert in the COMSOL API

Reference Manual.
This example demonstrates how to convert a quad mesh into a triangle mesh:
model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1', 2);
geom1.feature.create('c1', 'Circle');
geom1.feature.create('r1', 'Rectangle');
int1 = geom1.feature.create('int1', 'Intersection');
int1.selection('input').set({'c1' 'r1'});

72 |

CHAPTER 3: BUILDING MODELS

mesh1 = model.mesh.create('mesh1', 'geom1');

mesh1.feature.create('fq1', 'FreeQuad');
mesh1.runCurrent;
mesh1.feature.create('conv1', 'Convert');
mesh1.run;
mphmesh(model);

The result is illustrated in the Figure 3-15:

Figure 3-15: Mesh using free quad elements (left) and converted mesh from quad to
triangle (right).

Importing External Meshes and Mesh Objects

It is possible to import meshes to COMSOL Multiphysics using the following formats:
COMSOL Multiphysics text files (extension .mphtxt),
COMSOL Multiphysics binary files (extension .mphbin), and
NASTRAN files (extension .nas or .bdf).
IMPORTING MESHES TO THE COMMAND LINE

To import a mesh stored in a supported format use the Import feature. The following
commands import and plot a NASTRAN mesh for a crankshaft:
model = ModelUtil.create('Model');
model.geom.create('geom1', 3);
mesh1 = model.mesh.create('mesh1', 'geom1');
imp1 = mesh1.feature.create('imp1', 'Import');
model.modelPath('dir\COMSOL44\models\COMSOL_Multiphysics\
Structural_Mechanics')
imp1.set('filename','crankshaft.nas');

WO R K I N G W I T H M E S H E S

73

mesh1.feature('imp1').importData;
mesh1.run;
mphmesh(model);

Where dir is the path of root directory where COMSOL Multiphysics is installed. The
above command sequence results in Figure 3-16.

Figure 3-16: Imported NASTRAN mesh.

For additional properties supported, see Import in the COMSOL API
Reference Manual.
For a description of the text file format see the COMSOL Multiphysics
Reference Manual.

Measuring Mesh Quality

Use the stat method on the meshing sequence to get information on the mesh
quality. The quality measure is a scalar quantity, defined for each mesh element, where
0 represents the lowest quality and 1 represents the highest quality.
The following commands show how to visualize the mesh quality for a mesh on the
unit circle:
model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1', 2);
geom1.feature.create('c1', 'Circle');

74 |

CHAPTER 3: BUILDING MODELS

geom1.runAll;
mesh1 = model.mesh.create('mesh1', 'geom1');
mesh1.feature.create('ftri1', 'FreeTri');
mesh1.run;
meshdset1 = model.result.dataset.create('mesh1', 'Mesh');
meshdset1.set('mesh', 'mesh1');
pg1 = model.result.create('pg1', 2);
meshplot1 = pg1.feature.create('mesh1', 'Mesh');
meshplot1.set('data', 'mesh1');
meshplot1.set('filteractive', 'on');
meshplot1.set('elemfilter', 'quality');
meshplot1.set('tetkeep', '0.25');
mphplot(model,'pg1');
meshplot1.set('elemfilter','qualityrev');
meshplot1.run;
mphplot(model,'pg1');

These commands display the worst 25% and the best 25% elements in terms of mesh
element quality. In Figure 3-17, the triangular mesh elements in the right-hand side
plot are more regular than those in the left-hand side plot; this reflects the fact that a
quality measure of 1 corresponds to a uniform triangle, while 0 means that the triangle
has degenerated into a line.

Figure 3-17: Visualizations of the mesh quality: worst 25% (left) and best 25% (right).

Getting Mesh Statistics Information

Use the function mphmeshstats to get mesh statistics and mesh information where
stats is a structure containing the mesh statistics information. Enter:

WO R K I N G W I T H M E S H E S

75

stats = mphmeshstats(model);

The statistics structure has the following fields:

meshtag, the tag of the mesh sequence;
geomtag, the tag of the associated geometry;
isactive, Boolean variable that indicates if the mesh feature is active (1) or not (0);
hasproblems, Boolean variable that indicates if the mesh feature contains error or
warning nodes (1) or not (0);
iscomplete, Boolean variable that indicates if the mesh feature is built (1) or
not(0);
sdim, the space dimension of the mesh feature;
types, the element types present in the mesh. The element type can be vertex (vtx),
edge (edg), triangle (tri), quadrilateral (quad), tetrahedra (tet), pyramid (pyr),
prism (prism), hexahedra (hex). The type can also be of all elements of maximal
dimension in the selection (all);
numelem, number of elements for each element type;
minquality, minimum element quality;
meanquality, mean element quality;
qualitydistr, distribution of the element quality (20 values);
minvolume, minimum element volume/area;
maxvolume, maximum element volume/area; and
volume, total volume/area of the mesh.
If several mesh cases are available in the model object, specify the mesh tag:
stats = mphmeshstats(model, <meshtag>);

Getting and Setting Mesh Data

The function mphmeshstats also returns the mesh data such as element coordinates.
Use the function with two output variable to get the mesh data. Enter:
[meshstats,meshdata] = mphmeshstats(model);

where meshdata is a MATLAB structure with the following fields:

vertex, which contains the mesh vertex coordinates;

76 |

CHAPTER 3: BUILDING MODELS

 elem, which contains the element data information; and

elementity, which contains the element entity information for each element type.
EXAMPLE: EXTRACT AND CREATE MESH INFORMATION

A mesh can be manually created based on a grid generated in MATLAB. However,

before inserting this mesh into the model, a default coarse mesh is generated to get the
mesh information, which enables you to understand the requested mesh structure to
use with the createMesh method. Then a complete mesh can be constructed and
stored in the meshing sequence. If the geometry is not empty, the new mesh is checked
to ensure that it matches the geometry. In other words, to create an arbitrary mesh, an
empty geometry sequence and a corresponding empty meshing sequence need to be
created and the mesh is then constructed on the empty meshing sequence.
Start by creating a 2D model containing a square, and mesh it with triangles:
model = ModelUtil.create('Model');
model.modelNode.create('comp1');
geom1 = model.geom.create('geom1', 2);
geom1.feature.create('sq1', 'Square');
geom1.run;
mesh1 = model.mesh.create('mesh1', 'geom1');
mesh1.feature.create('ftri1', 'FreeTri');
mesh1.feature('size').set('hmax', '0.5');
mesh1.run('ftri1');
mphmesh(model);

To get the mesh data information, enter:

[meshstats,meshdata] = mphmeshstats(model);

WO R K I N G W I T H M E S H E S

77

meshdata =
vertex: [2x12 double]
elem: {[2x8 int32] [3x14 int32]
elementity: {[8x1 int32] [14x1 int32]

[0 5 7 11]}
[4x1 int32]}

The mesh node coordinates are stored in the vertex field:

vtx = meshdata.vertex
vtx =
Columns 1 through 7
0
0.5000
0.3024
0
0.6314
0
0
0.3023
0.5000
0.3632
Columns 8 through 12
0
0.6730
1.0000 0.5000
1.0000
1.0000
0.6728
0.5000 1.0000
1.0000

1.0000
0

0.3511
0.6397

In the elem field the element information is retrieved, such as the node indices (using
a 0 based) connected to the elements:
tri = meshdata.elem{2}
tri =
Columns 1 through 5
0
3
1
0
2
2
Columns 6 through 10
6
7
2
3
4
6
Columns 11 through 14
10
10
7
6
6
8

1
4
2

1
5
4

6
3
2

6
4
8

5
9
4

9
8
4

9
11
8

11
10
8

In the above command, notice that element number 1 is connected to nodes 1, 2, and
3, and element number 2 is connected to nodes 4, 1, and 3.
Then create manually a mesh using a data distribution generated in MATLAB. Enter
the command:
[x,y] = meshgrid([0 0.5 1], [0 0.5 1]);
X = reshape(x,1,9);
Y = reshape(y,1,9);
coord=[X;Y];

78 |

CHAPTER 3: BUILDING MODELS

The node distribution obtained with this command corresponds to the mesh in
Figure 3-18.

4
3
2

7
6

Figure 3-18: Mesh with elements (bold) and nodes (italic) indices.
Table 3-1 lists the nodes and element connectivity in the mesh.
TABLE 3-1: ELEMENT AND NODES CONNECTIVITY
ELEMENT

NODES

1, 4, 5

1, 2, 5

2, 5, 6

2, 3, 6

4, 7, 8

4, 5, 8

5, 8, 9

5, 6, 9

To create the elements and nodes connectivity information use the command:
new_tri(:,1)=[0;3;4];
new_tri(:,2)=[0;1;4];
new_tri(:,3)=[1;4;5];
new_tri(:,4)=[1;2;5];
new_tri(:,5)=[3;6;7];
new_tri(:,6)=[3;4;7];
new_tri(:,7)=[4;7;8];
new_tri(:,8)=[4;5;8];

WO R K I N G W I T H M E S H E S

79

Assign the element information, node coordinates, and elements connectivity

information, into a new mesh. Use the method createMesh to create the new mesh:
geom2 = model.geom.create('geom2',2);
mesh2 = model.mesh.create('mesh2','geom2');
mesh2.data.setElem('tri',new_tri)
mesh2.data.setVertex(coord)
mesh2.data.createMesh

80 |

CHAPTER 3: BUILDING MODELS

M o de li ng P hy s i cs
This section describes how to set up physics interfaces in a model. The physics interface
defines the equations that COMSOL solves.
The Physics Interface Syntax
The Material Syntax
Modifying the Equations
Adding Global Equations
Defining Model Settings Using External Data File
Access the User-Defined Physics Interface

The Physics Interfaces in the COMSOL Multiphysics Reference Manual

The links to features described outside of this user guide do not work in
the PDF, only from the online help.

The Physics Interface Syntax

Create a physics interface instance using the syntax:
model.physics.create(<phystag>, physint, <geomtag>);

where <phystag> is a string that identifies the physics interface. Once defined, you can
always refer to a physics interface, or any other feature, by its tag. The string physint
is the constructor name of the physics interface. To get the constructor name, the best
way is to create a model using the desired physics interface in the GUI and save the
model as an M-file. The string <geomtag> refers to the geometry where you want to
specify the interface.
To add a feature to a physics interface, use the syntax:
model.physics(<phystag>).feature.create(<ftag>,operation);

where the <phystag> string refers to a physics interface. <ftag> is a string that you
use to refer to the operation. To set a property to a value in a operation, enter:

MODELING PHYSICS

81

model.physics(<phystag>).feature(<ftag>).set(property, <value>);

where <ftag> is the string that identifies the feature.

There are alternate syntaxes available. See model.physics() in the

COMSOL API Reference Manual.
To disable or remove a feature node, use the methods active or remove, respectively.
The command:
model.physics(<phystag>).feature(<ftag>).active(false);

disables the feature <ftag>.

To activate the feature node you can set the active method to true:
model.physics(<phystag>).feature(<ftag>).active(true);

To remove a feature from the model, use the method remove:

model.physics(<phystag>).feature.remove(<ftag>);
E X A M P L E : I M P L E M E N T A N D S O L VE A H E A T TR A N S F E R P RO BL E M

This example shows how to add a physics interface and set the boundary conditions in
the model object.
Start to create a model object including a 3D geometry. The geometry consists in a
block with default settings. Enter the following commands at the MATLAB prompt:
model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1', 3);
geom1.feature.create('blk1', 'Block');
geom1.run;

Add a Heat Transfer in Solids interface to the model:

phys = model.physics.create('ht', 'HeatTransfer', 'geom1');

The tag of the interface is ht. The interface constructor is HeatTransfer. The physics
is defined on geometry geom1.
The physics interface automatically creates a number of default features. To examine
these, enter:
model.physics('ht')
ans =

82 |

CHAPTER 3: BUILDING MODELS

Type: Heat Transfer in Solids

Tag: ht
Identifier: ht
Operation: HeatTransfer
Child nodes: solid1, ins1, cib1, init1, os1

The physics method has the following child nodes: solid1, ins1, cib1, init1, and
os1. These are the default features that come with the Heat Transfer in Solids
interface. The first feature, solid1, consists of the heat balance equation. Confirm this
by entering:
solid = phys.feature('solid1')
ans =
Type: Heat Transfer in Solids
Tag: solid1

The settings of the solid1 feature node can be modified, for example, to manually set
the material property. To change the thermal conductivity to 400 W/(m*K) enter:
solid.set('k_mat', 1, 'userdef');
solid.set('k', '400');

The Heat Transfer in Solids interface has features you can use to specify domain or
boundary settings. For example, to add a heat source of 105 W/m3 in the study
domain, enter the commands:
hs = phys.feature.create('hs1', 'HeatSource', 3);
hs.selection.set([1]);
hs.set('Q', 1, '1e5');

To create a temperature boundary condition on boundaries 3, 5, and 6, enter:

temp = phys.feature.create('temp1', 'TemperatureBoundary', 2);
temp.selection.set([3 5 6]);
temp.set('T0', 1, '300[K]');

Then add a mesh and a study feature and compute the solution:
model.mesh.create('mesh1', 'geom1');
std = model.study.create('std1');
std.feature.create('stat', 'Stationary');
std.run

To visualize the solution, create a 3D surface plot group, which is displayed in a

MATLAB figure with the function mphplot:
pg = model.result.create('pg1', 'PlotGroup3D');
pg.feature.create('surf1', 'Surface');
mphplot(model,'pg1','rangenum',1)

MODELING PHYSICS

83

The Material Syntax

In addition to changing material properties directly inside the physics interfaces,
materials available in the entire model can also be created. Such a material can be used
by all physics interfaces in the model.
Create a material using the syntax:
model.material.create(<mattag>);

where <mattag> is a string that you use to refer to a material definition.

A Material is a collection of material models, where each material model defines a set
of material properties, material functions, and model inputs. To add a material model,
use the syntax:
model.material(<mattag>).materialmodel.create(<mtag>);

where <mattag> is the string identifying the material defined when creating the
material. The string <mtag> refers to the material model.
To define material properties for the model, set the property value pairs by entering:
model.material(<mattag>).materialmodel(<mtag>).set(property,
<value>);
EXAMPLE: CREATE A MATERIAL NODE

The section Example: Implement and Solve a Heat Transfer Problem shows how to
change a material property inside a physics interface. This example shows how to

84 |

CHAPTER 3: BUILDING MODELS

define a material available globally in the model. These steps assume that the previous
example has been followed. Enter:
mat = model.material.create('mat1');

The material automatically creates a material model, def, which can be used to set up
basic properties. For example, use it to define the density and the heat capacity:
mat.materialmodel('def').set('density', {'400'});
mat.materialmodel('def').set('heatcapacity', {'2e3'});

To use the defined material in a model, set the solid1 feature to use the material node.
Enter:
solid.set('k_mat',1,'from_mat');

model.material() in the COMSOL API Reference Manual

Modifying the Equations

The equation defining the physics node can be edited with the method
featureInfo('info') applied to a feature of the physics node
physics(<phystag>).feature(<ftag>), where <phystag> and <ftag> identify
the physics interface and the feature, respectively:
info =
model.physics(<phystag>).feature(<ftag>).featureInfo('info');

Use the method getInfoTable(type) to return the tables available in the Equation
View node:
infoTable = info.getInfoTable(type);

where type defines the type of table to return. It can have the value 'Weak' to return
the weak form equations, 'Constraint' to return the constraint types table, or
'Expression' to return the variable expressions table.
EXAMPLE: ACCESS AND MODIFY THE EQUATION WEAK FORM

This example continues from the Example: Implement and Solve a Heat Transfer
Problem and modifies the model equation.
To retrieve information about the physics interface create an info object:
info = model.physics('ht').feature('solid1').featureInfo('info');

MODELING PHYSICS

85

From the info object access the weak form equation by entering:
infoTable = info.getInfoTable('Weak');

This returns a string variable that contains both the name of the weak equation variable
and the equation of the physics implemented in the weak form. Enter the command:
list = infoTable(:)

which results in the output:

list =
java.lang.String[]:
[1x159 char]
'root.comp1.ht.solid1.weak$1'
'Material'
'Domain 1'

The output shows that the physics is defined with the weak expression available in the
variable list(1). Enter:
list(1)

to get the weak equation as a string variable. The result of this command is:
ans =
-(ht.k_effxx*Tx+ht.k_effxy*Ty+ht.k_effxz*Tz)*test(Tx)-(ht.k_effyx
*Tx+ht.k_effyy*Ty+ht.k_effyz*Tz)*test(Ty)-(ht.k_effzx*Tx+ht.k_eff
zy*Ty+ht.k_effzz*Tz)*test(Tz)

To access the equation in the node root.comp1.ht.solid1.weak$1; for example, to

modify the equation and lock the expression, run the commands:
equExpr = '200[W/(m*K)]*(-Tx*test(Tx)-Ty*test(Ty)-Tz*test(Tz))';
info.lock(list(2), {equExpr});

These commands set the heat conductivity to a constant value directly within the heat
balance equation.

Adding Global Equations

To add a global equation in the model use the command:
model.physics.create(<odestag>, 'GlobalEquations');

To define the name of the variable to be solved by the global equation, enter:
model.physics(<odetag>).set('name', <idx>, <name>);

where <idx> is the index of the global equation, and <name> a string with the name
of the variable.

86 |

CHAPTER 3: BUILDING MODELS

Set the expression <expr> of the global equation with:

model.physics(<odetag>).set('equation', <idx>, <expr>);

where <expr> is defined as a string variable.

Initial value and initial velocity can be set with the commands:
model.physics(<odetag>).set('initialValueU', <idx>, <init>);
model.physics(<odetag>).set('initialValueUt', <idx>, <init_t>);

where <init> and <init_t> are the initial value expression for the variable and its
time derivative respectively.
EXAMPLE: SOLVE AN ODE PROBLEM

This example illustrates how to solve the following ODE in a COMSOL model:

u
u + --- + 1 = 0
2
u0 = 0

u 0 = 20
model = ModelUtil.create('Model');
ge = model.physics.create('ge', 'GlobalEquations');
ge1 = ge.feature('ge1');
ge1.set('name', 1, 1, 'u');
ge1.set('equation', 1, 1, 'utt+0.5*ut+1');
ge1.set('initialValueU', 1, 1, 'u0');
ge1.set('initialValueUt', 1, 1, 'u0t');
model.param.set('u0', '0');
model.param.set('u0t', '20');
std1 = model.study.create('std1');
std1.feature.create('time', 'Transient');
std1.feature('time').set('tlist', 'range(0,0.1,20)');
std1.run;
model.result.create('pg1', 1);
model.result('pg1').set('data', 'dset1');
model.result('pg1').feature.create('glob1', 'Global');
model.result('pg1').feature('glob1').set('expr', {'mod1.u'});
mphplot(model,'pg1')

MODELING PHYSICS

87

Defining Model Settings Using External Data File

To use tabulated data from files in a model, use the interpolation function available
under the Global Definitions node or the Definitions node of the model.
To add an interpolation function to the manual, enter:
model.func.create(<functag>, 'Interpolation');

The interpolation function is initially defined globally and is located in the Model
Builder on the COMSOL Desktop under the Global Definitions node. If you have
several model nodes in your model and you want to attach it to the specified model
node <model>, enter:
model.func(<functag>).model(<model>);

where <model> is the tag of the model node to attach the interpolation function.
Then you can interpolate data specified by a table inside the function (default), or
specified in an external file.
When using an interpolation table, set the interpolation data for each row of the table
with the commands:
model.func(<functag>).setIndex('table', <t_value>, <i>, 1);
model.func(<functag>).setIndex('table', <ft_value>, <i>, 2);

where <t_value> is the interpolation parameter value and <ft_value> is the function
value. <i> is the index (0-based) in the interpolation table.

88 |

CHAPTER 3: BUILDING MODELS

To use an external file change the source for the interpolation and specify the file,
where filename is the name (including the path) of the data file:
model.func(<functag>).set('source', 'file');
model.func(<functag>).set('filename', <filename>);

Several interpolation methods are available. Choose the one to use with the command:
model.func(<functag>).set('interp', method);

The string method can be set as one of the following alternatives:

'neighbor', for interpolation according to the nearest neighbor method,
'linear', for linear interpolation method,
'cubicspline', for cubic spline interpolation method, or
'piecewisecubic', piecewise cubic interpolation method.
You can also decide how to handle parameter values outside the range of the input data
by selecting an extrapolation method:
model.func(<functag>).set('extrap', method);

The string method can be one of these values:

'const', to use a constant value outside the interpolation data,
'linear', for linear extrapolation method,
'nearestfunction', to use the nearest function as extrapolation method, or
'value', to use a specific value outside the interpolation data.

model.func() in the COMSOL API Reference Manual

Access the User-Defined Physics Interface

Follow the instructions in this section to run a model made with a user-defined physics
interface created with the COMSOL Physics Builder.

The COMSOL Physics Builder Manual.

MODELING PHYSICS

89

These instructions assume that you already have a Physics Builder

development file available under the Development Files section. If you
have not created the physics interface yourself, you need the associated
plug-in JAR-file and you can jump to step 5.
1 Compile your development file to an archive folder by right-clicking the
Development Files node and selecting Compile to Archive Folder.
2 In the Choose Archive Folder window, browse to the desired archive folder and click
OK.

The archive folder name has to start to follow the syntax

com.comsol.<name>, where <name> is a name of your choice.
3 Right-click the archive folder and select Compact Archive.
4 Right-click the archive folder and select Export as Plugin. Choose a destination folder

and click OK.

5 Copy and paste the file that you have just saved, com.comsol.<name>.jar, to the

plugins folder of the COMSOL installation.

6 In the bin folder of the COMSOL installation open the file comsolpath.txt and

add com.comsol.<name>.jar to the list.

7 When you start COMSOL with MATLAB, the dynamic Java path is automatically

updated with the path to the new JAR-file. You can verify this by typing
javaclasspath at the MATLAB prompt.

90 |

CHAPTER 3: BUILDING MODELS

C r e a ti ng S e le ct i on s
In this section:
The Selection Node
Coordinate-Based Selections
Selection Using Adjacent Geometry
Displaying Selections

Named Selections

The links to features described outside of this user guide do not work in
the PDF, only from the online help.

The Selection Node

Use a Selection node to define a collection of geometry entities in a central location in
the model. The selection can easily be accessed in physics or mesh features or during
results analysis. For example, you can refer collectively to a set of boundaries that have
the same boundary conditions, which also have the same mesh size settings.
A selection feature can be one of these types:
explicit, to include entities explicitly defined by their definitions indices,
ball, to include entities that fall with a set sphere, and
box, to include entities that fall within a set box.
Selection can also be combined by Boolean operations, such as Union, Intersection,
and Difference.
SETTING AN EXPLICIT SELECTION

Create an explicit selection with the command:

model.selection.create(<seltag>, 'Explicit');

To specify the domain entity dimension to use in the selection node, enter:

CREATING SELECTIONS

91

model.selection(<seltag>).geom(sdim);

where sdim is the space dimension that represents the different geometric entities:
3 for domains,
2 for boundaries/domains,
1 for edges/boundaries, and
0 for points.
Set the domain entity indices in the selection node with the command:
model.selection(<seltag>).set(<idx>);

where <idx> is an array of integers that list the geometric entity indices to add in the
selection.

Coordinate-Based Selections
DEFINING A BALL SELECTION NODE

The Ball selection node is defined by a center point and a radius. The selection can
include geometric entities that are completely or partially inside the ball. The selection
can be set up by using either the COMSOL API directly or the mphselectcoords
function. There are different ways to define the ball selections: Ball Selection Using the
COMSOL API or Ball Selection Using mphselectcoords.

Ball Selection Using the COMSOL API

To add a ball selection to a model object enter:
model.selection.create(<seltag>, 'Ball');

To set the coordinates (<x0>, <y0>, <z0>) of the selection center point, enter:
model.selection(<seltag>).set('posx', <x0>);
model.selection(<seltag>).set('posy', <y0>);
model.selection(<seltag>).set('posz', <z0>);

where <x0>, <y0>, <z0> are double values.

Specify the ball radius <r0> with the command:
model.selection(<seltag>).set('r', <r0>);

where <r0> is a double floating-point value.

To specify the geometric entity level, enter:
model.selection(<seltag>).set('entitydim', edim);

92 |

CHAPTER 3: BUILDING MODELS

where edim is an integer defining the space dimension value (3 for domains, 2 for
boundaries/domains, 1 for edges/boundaries, and 0 for points).
The selection also specifies the condition for geometric entities to be selected:
model.selection(<seltag>).set('condition', condition);

where condition can be:

'inside', to select all geometric entities completely inside the ball,
'intersects', to select all geometric entities that intersect the ball (default),
'somevertex', to select all geometric entities where at least some vertex is inside
the ball, or
'allvertices', to select all geometric entities where all vertices are inside the ball.

Ball Selection Using mphselectcoords

The function mphselectcoords retrieves geometric entities enclosed by a ball.
To get the geometric entities enclosed by a ball of radius r0, with its center positioned
at (x0,y0,z0) enter the command:
idx = mphselectcoords(model, <geomtag>, [<x0>,<y0>,<z0>], ...
entitytype,'radius',<r0>);

where <geomtag> is the tag of geometry where the selection, and entitytype, can be
one of 'point', 'edge', 'boundary', or 'domain'.
The above function returns the entity indices list. Use it to specify a feature selection
or to create an explicit selection as described in Setting an Explicit Selection.
By default the function searches for the geometric entity vertices near these
coordinates using the tolerance radius. It returns only the geometric entities that have
all vertices inside the search ball. To include any geometric entities in the selection that
have at least one vertex inside the search ball, set the property include to 'any':
idx = mphselectcoords(model, <geomtag>, [<x0>,<y0>,<z0>], ...
entitytype,'radius',<r0>,'include','any');

In case the model geometry is finalized as an assembly, you have distinct geometric
entities for each part of the assembly (pair). Specify the adjacent domain index to avoid
selection of any overlapping geometric entities. Set the adjnumber property with the
domain index:
idx = mphselectcoords(model, <geomtag>, [<x0>,<y0>,<z0>], ...
entitytype,'radius',<r0>,'adjnumber',<idx>);

where <idx> is the domain index adjacent to the desired geometric entities.

CREATING SELECTIONS

93

DEFINING A BOX SELECTION NODE

The Box selection node is defined by two diagonally opposite points of a box (in 3D)
or rectangle (in 2D). There are different ways to define the box selections: Box
Selection Using the COMSOL API or Box Selection Using mphselectbox

Box Selection Using the COMSOL API

This command adds a box selection to the model object:
model.selection.create(<seltag>, 'Box');

To specify the points (<x0>, <y0>, <z0>) and (<x1>, <y1>, <z1>), enter:
model.selection(<seltag>).set('xmin',
model.selection(<seltag>).set('ymin',
model.selection(<seltag>).set('zmin',
model.selection(<seltag>).set('xmax',
model.selection(<seltag>).set('ymax',
model.selection(<seltag>).set('zmax',

<x0>);
<y0>);
<z0>);
<x1>);
<y1>);
<z1>);

where <x0>, <y0>, <z0>, <x1>, <y1>, <z1> are double values.
To specify the geometric entities levels use the command:
model.selection(<seltag>).set('entitydim', edim);

where edim is an integer defining the space dimension value (3 for domains, 2 for
boundaries/domains, 1 for edges/boundaries, and 0 for points).
The selection also specifies the condition for geometric entities to be selected:
model.selection(<seltag>).set('condition', condition);

where condition can be:

'inside', to select all geometric entities completely inside the ball,
'intersects', to select all geometric entities that intersect the ball (default),
'somevertex', to select all geometric entities where at least some vertex is inside
the ball, or
'allvertices', to select all geometric entities where all vertices are inside the ball.

Box Selection Using mphselectbox

The function mphselectbox retrieves geometric entities enclosed by a box (in 3D) or
rectangle (in 2D).
To get the geometric entities of type entitytype enclosed by the box defined by the
points (x0,y0,z0) and (x1,y1,z1), enter the command:
idx = mphselectbox(model,<geomtag>,...

94 |

CHAPTER 3: BUILDING MODELS

[<x0> <x1>;<y0> <y1>;<z0> <z1>], entitytype);

where <geomtag> is the geometry tag where the selection is applied, and entitytype
can be one of 'point', 'edge', 'boundary', or 'domain'.
The above function returns the entity indices list. Use it to specify a feature selection
or to create an explicit selection as described in Setting an Explicit Selection.
By default the function searches for the geometric entity vertices near these
coordinates using the tolerance radius. It returns only the geometric entities that have
all vertices inside the box or rectangle. To include any geometric entities in the
selection that have at least one vertex inside the search ball, set the property include
to 'any':
idx = mphselectbox(model,<geomtag>,...
[<x0> <x1>;<y0> <y1>;<z0> <z1>], entitytype,'include','any');

In case the model geometry is finalized as an assembly (pair), you have distinct
geometric entities for each part of the assembly. Specify the adjacent domain index to
avoid selection of overlapping geometric entities. Set the adjnumber property with the
domain index:
idx = mphselectbox(model,<geomtag>,...
[<x0> <x1>;<y0> <y1>;<z0> <z1>], entitytype, 'adjnumber', <idx>);

where <idx> is the domain index adjacent to the desired geometric entities.
RETRIEVING POINT COORDINATES USING A SELECTION

Use mphgetcoords to retrieve coordinates of the points that belong to a given

geometry. Run the command below to get the coordinates of the points that belong
to the desired geometric entity:
c = mphgetcoords(model,<geomtag>,entitytype,<idx>);

where <geomtag> is the geometry tag where the selection is applied, entitytype can
be one of 'point', 'edge', 'boundary', or 'domain' and <idx> is a integer array
containing the geometric entity indices. c is a Nx2 double array containing the point
coordinates where N is the number of points.

Selection Using Adjacent Geometry

Another approach is to select geometric entities and define the adjacent object. For
example, select edges adjacent to a specific domain or boundaries adjacent to a specific
point. There are different ways to create an adjacent selection: Adjacent Selection
Using the COMSOL API or Adjacent Selection Using mphgetadj

CREATING SELECTIONS

95

Adjacent Selection Using the COMSOL API

This command creates a selection node using adjacent geometric entities:
model.selection.create(<seltag>, 'Adjacent');

The geometric entity level needs to be specified with the command:

model.selection(<seltag>).set(edim);

where edim is an integer defining the space dimension value (3 for domains, 2 for
boundaries/domains, 1 for edges/boundaries, and 0 for points).
The Adjacent selection node only supports the Selection node as an input:
model.selection(<seltag>).set( 'Adjacent');

and specify the ball radius <r0> with the command:

model.selection(<seltag>).set('input', <seltag>);

where <seltag> is the tag of an existing Selection node.

Select the level of geometric entities to add in the selection with the command:
model.selection(<seltag>).set('outputdim', edim);

where edim is an integer defining the space dimension value (3 for domains, 2 for
boundaries/domains, 1 for edges/boundaries, and 0 for points).
If there are multiple domains in the geometry to include in the interior and exterior
selected geometric entities, then enter:
model.selection(<seltag>).set('interior', 'on');
model.selection(<seltag>).set('exterior', 'on');

To exclude the interior/exterior, select geometric entities and set the respective
property to 'off'.

Adjacent Selection Using mphgetadj

An alternative to the COMSOL API is to use the function mphgetadj to select
geometric entities using an adjacent domain.
To get a list of entities of type entitytype adjacent to the entity with the index
<adjnumber> of type adjtype, enter:
idx = mphselectbox(model, <geomtag>, entitytype, ...
adjtype, <adjnumber>);

where <geomtag> is the tag of geometry where the selection applies. The string
variables entitytype and adjtype can be one of 'point', 'edge', 'boundary', or
'domain'.

96 |

CHAPTER 3: BUILDING MODELS

The list returned by the function can be used to specify the selection for a model
feature or to create an explicit selection as described in Setting an Explicit Selection.

Displaying Selections
Use the function mphviewselection to display the selected geometric entities in a
MATLAB figure. This section also includes sections to Specify What to Display with
the Selection and Change Display Color and Transparency.
You can either specify the geometry entity index and its entity type or specify the tag
of a selection node available in the model.
To display the entity of type entitytype with the index <idx> enter:
mphviewselection(model, <geomtag>, <idx>, entitytype)

where <geomtag> is the geometry node tag, and <idx> is a positive integer array that
contains the entity indices. The string entitytype can be one of 'point', 'edge',
'boundary', or 'domain'.
If the model contains a selection node with the tag <seltag>, this selection can be
displayed with the command:
mphviewselection(model, <seltag>)

To plot the selection in an existing axis, set the property 'parent' with the axis output
value. For instance, the command below displays the selection in the current axis:
mphviewselection(model, <seltag>,'parent',gca)

Specify the render to display the figure with the property 'renderer' you can use
Open GL or Z buffer with the value 'opengl' or 'zbuffer' respectively.
SPECIFY WHAT TO DISPLAY WITH THE SELECTION

If the selected selection node is a Ball or Box selection, the ball or box selector is
display by default, to not show the selector, set the property 'showselector' to
'off'.
mphviewselection(model, <seltag>, 'showselector', 'off')

To deactivate the geometry representation, set the property 'geommode' to 'off'

as in this command:
mphviewselection(model, <seltag>, 'geommode', 'off')

CREATING SELECTIONS

97

 The property 'vertexmode', 'edgemode' and 'facemode' support the value

'on' or 'off' in order to render the vertex, the edge and the face respectively in
the figure, as in this example line:
mphviewselection(model, <seltag>, 'facemode', 'off')

To include vertex, edge and face number, set the property 'vertexlabels',
'facelabels' and 'edgelabels' respectively to 'on'.
Change the marker used to represent the vertex with the property 'facemode'. In
the example command below the vertex are represented in the figure with a '+'
marker instead of the default '.':
mphviewselection(model, <seltag>, 'marker', '+')

Specify the size of the marker with the property 'edgelabels', you can specify an
integer value corresponding to the number of pixels.
C H A N G E D I S P L AY C O L O R A N D TR A N S P A RE N C Y

To change the color of the edge and the face use the property 'edgecolor' and
'facecolor' respectively. Specify the color of the vertex with the property
'markercolor'. Set the property with a character or using a RGB array. In this
example the edges are displayed in blue while the faces are displayed in the color
defined by the RGB array (0.5,0.5,0.5):
mphviewselection(model, <seltag>, 'edgecolor', 'b', ...
'facecolor', [0.5 0.5 0.5])

Specify the color for the selected edge and face with the properties
'edgecolorselected' and 'facecolorselected' respectively. Specify the color
of the selected vertex with the property 'markercolorselected'. Use a character
or specify the color by its RGB array. These commands show how to set the edge to
a blue color and the face with the color defined by the RGB array (0.5, 0.5,0.5):
mphviewselection(model, <seltag>, 'edgecolorselected', 'b', ...
'facecolorselected', [0.5 0.5 0.5])

Specify the color for the vertex, edge, and face labels with the properties
'vertexlabelscolor', 'edgelabelscolor' and 'facelabelscolor' respectively.
You can use a character or the RGB array to specify the color.
Control the transparency of the geometry representation with the property
'facealpha'. Set the property with a double included between 0 and 1. Using this
command the geometry is displayed with a transparency of 50%:
mphviewselection(model, <seltag>, 'facealpha', 0.5)

98 |

CHAPTER 3: BUILDING MODELS

 Control the transparency of the selector representation with the property

'selectoralpha'. Set the property with a double included between 0 and 1.
Using this command, the selector is displayed with plain color:
mphviewselection(model, <seltag>, 'selectoralpha', 1)

CREATING SELECTIONS

99

Computing the Solution

This section describes the commands to use to compute the solution at the MATLAB
prompt. How to set up and run a study node but also how to set manual solver
sequence. This includes the following paragraphs:
The Study Node
The Solver Sequence Syntax
Run the Solver Sequence
Adding a Parametric Sweep
Adding a Job Sequence
Plot While Solving
Introduction to Solvers and Studies in the COMSOL Multiphysics
Reference Manual
Solver in the COMSOL API Reference Manual

The links to features described outside of this user guide do not work in
the PDF, only from the online help.

The Study Node

A study node holds the nodes that define how to solve a model. These nodes are
divided into these broad categories:
Study steps, which determines overall settings suitable for a certain study type,
Solver sequence, and
Job configurations for distributed parametric jobs, batch jobs, and cluster
computing.

Introduction to Solvers and Studies in the COMSOL Reference Manual

100 |

CHAPTER 3: BUILDING MODELS

Create a study node by using the syntax:

model.study.create(<studytag>);

where studytag is a string that is used to define the study node.

The minimal definition for the study node consists in a study step that define the type
of study to use to compute the solution. To add a study step to the study node, use the
syntax:
model.study(<studytag>).feature.create(<ftag>, operation);

where <studytag> is the string identifying the study node. The string <ftag> is a
string that is defined to refer to the study step. The string operation is one of the basic
study types, such as Stationary, Transient, or Eigenfrequency, and more.
To specify a property value pair for a study step, enter:
model.study(<studytag>).feature(<ftag>).set(property, <value>);

where <ftag> is the string identifying the study step.

To generate the default solver sequence associated with the physics solved in the model
and compute the solution, run the study node with the command:
model.study(<studytag>).run

model.study() in the COMSOL API Reference Manual

The Solver Sequence Syntax

If you do not want to use the default solver sequence created by the study node, you
can manually create one. To create a solver sequence, enter:
model.sol.create(<soltag>);

where <soltag> is a string used to refer to the solver sequence associated to a solution
object.
A solver sequence has to be connected to a study node, which is done with the
command:
model.sol(<soltag>).study(<studytag>);

COMPUTING THE SOLUTION

101

where <studytag> is the tag of the study you want to associate the solver sequence
defined with the tag <soltag>.
A solver sequence also requires the definition of these nodes:
Study Step, where the study and study step is specified for compiling the equations
and computing the current solver sequence;
Dependent Variables, this node handles settings for the computation of dependent
variables, such as initial value and scaling settings but also the dependent variables
not solved for; and
Solver node, where the type of solver to use is specified to compute the solution.
Add the nodes to the solver sequence with the command:
model.sol(<soltag>).feature.create(<ftag>, operation);

where <soltag> is the string defined when creating the solver sequence. The string
ftag is a string that is defined to refer to the node, for example, a study step.
operation can be 'StudyStep', 'Variables', or 'Stationary'.
To specify a property value pair for a solver feature, enter:
model.sol(<soltag>).feature(<ftag>).set(property, <value>);

where <soltag> is a string referring to the solver sequence configuration.

For a list of the operations available for the solver node, see Features
Producing and Manipulating Solutions and Solver, in the COMSOL API
Reference Manual.

Run the Solver Sequence

There are different ways to run the solver sequence:
run the entire sequence,
run up to a specified feature, or
run from a specified feature.
Use the methods run or runAll to run the entire solver configuration node:
model.sol(<soltag>).run;
model.sol(<soltag>).runAll;

102 |

CHAPTER 3: BUILDING MODELS

You can also use the method run(<ftag>) to run the solver sequence up to the solver
feature with the tag <ftag>:
model.sol(<soltag>).run(<ftag>);

When you want to continue solving a sequence, use the method runFrom(<ftag>) to
run the solver configuration from the solver feature with the tag <ftag>:
model.sol(<soltag>).runFrom(<ftag>)

Adding a Parametric Sweep

In addition to the study step that defines a study type, you can add a parametric sweep
to the study node. This is a study step that does not generate equations and can only
be used in combination with other study steps. You can formulate the sequence of
problems that arise when some parameters are varied in the model.
To add a parametric sweep to the study node, enter:
model.study(<studytag>).feature.create(<ftag>, 'Parametric');

where <studytag> is the tag of the study node where to include the parametric sweep
defined with the tag <ftag>.
To add one or several parameters to the sweep, enter the command:
model.study(<studytag>).feature(<ftag>).setIndex('pname',
<pname>, <idx>);

where <pname> is the name of the parameter to use in the parametric sweep and <idx>
the index number of the parameter. Set the <idx> to 0 to define the first parameter, 1
to define the second parameter, and so on.
Set the list of the parameter values with the command:
model.study(<studytag>).feature(<ftag>).setIndex('plistarr',
<pvalue>, <idx>);

where <pvalue> contains the list of parameter values defined with either a string or
with a double array, and <idx> is the index number of the parameter and uses the same
value as for the parameter name.
If there are several parameters listed in the parametric sweep node, select the type of
sweep by entering:
model.study(<studytag>).feature(<ftag>).set('sweeptype', type);

COMPUTING THE SOLUTION

103

where the sweep type,type, can be either 'filled' or 'sparse', referring to all
combinations or specified combinations of the parameter values, respectively.

Adding a Job Sequence

In the study node you can define a job sequence such as distributed parametric jobs,
batch jobs, and cluster computing. To create a batch node enter:
model.batch.create(<batchtag>, type);

where <batchtag> is the tag of the job sequence and type is the type of job to define.
It can be either Parametric, Batch, or Cluster.
For a solver sequence you need to attach the job sequence to an existing study node.
Enter the command:
model.batch(<batchtag>).atached(<studytag>);

where <studytag> is the tag of the study node.

Each job type, such as parametric, batch, or cluster job, can be defined with specific
properties. Use the set method to add a property to the batch job:
model.batch(<batchtag>).set(property, <value>);

You can get the list of the properties in model.batch() in the COMSOL
API Reference Manual.
To run the batch sequence use the run method:
model.batch(<batchtag>).run;

Plot While Solving

With the Plot While Solving functionality you can monitor the development of the
computation by updating predefined plots during the computation. Since the plots are
displayed on a COMSOL Multiphysics graphics window, start COMSOL with
MATLAB using a graphics server.

See the COMSOL Installation Guide to start COMSOL with MATLAB

using a graphics server.

104 |

CHAPTER 3: BUILDING MODELS

To activate Plot While Solving, enter the command:

model.study(<studytag>).feature(<studysteptag>).set('plot',
'on');

where <studytag> and <studysteptag> refer to the study node and study step,
respectively.
Specify the plot group to plot by setting the plot group tag:
model.study(<studytag>).feature(<studysteptag>).set('plotgroup',
<ptag>);

Only one plot group can be plotted during a computation. Use the probe feature
instead if you need to monitor several variables.
To activate Plot While Solving for a probe plot, enter the command:
model.study(<studytag>).feature(<studysteptag>).set('probesel',
seltype);

where seltype is the type of probe selection, that can be 'none', 'all', or
'manual'.
In case the probe selection is set to manual you have to specify the list of the probe
variable to display. Enter the command:
model.study(<studytag>).feature(<studysteptag>).set('probes',
<list>);

where <list> is the a cell array containing the list of the probe to use.

COMPUTING THE SOLUTION

105

Analyzing the Results

In this section:
The Plot Group Syntax
Displaying The Results
The Data Set Syntax
The Numerical Node Syntax
Exporting Data
Postprocessing and Analyzing Results in the COMSOL Multiphysics
Reference Manual
Results in the COMSOL API Reference Manual

The links to features described outside of this user guide do not work in
the PDF, only from the online help.

The Plot Group Syntax

Result plots always appear in plot groups, which are added to the model by the create
method:
model.result.create(<pgtag>, sdim);

Select the string <pgtag> to identify the plot group and the integer sdim to set the
space dimension (1, 2, or 3) of the group.
To add a plot to a plot group, use the syntax:
model.result(<pgtag>).feature.create(<ftag>, plottype);

where the string <ftag> identifies the plot, and the string plottype defines its type.
Plots can have different attributes that modify the display. For example, the
Deformation attribute deforms the plot according to a vector quantity, the Height
Expression attribute introduces 3D height on a 2D table surface plot, and the Filter
attribute filters the plot using a logical expression. The type of plot determines which
attributes are available. Add an attribute to a plot with the command:

106 |

CHAPTER 3: BUILDING MODELS

model.result(<pgtag>).feature(<ftag>).feature.create(<attrtag>,
attrtype);

where attrtype is a string that defines the attribute type.

For a list of available plot types and corresponding attribute types, see
Results and model.result() in the COMSOL API Reference Manual.

Displaying The Results

There are different commands available to Display Plot Groups, Extract Plot Data,and
to Plot External Data. A practical example of this is included in Example: Plot mpheval
Data.
DISPLAY PLOT GROUPS

Use the command mphplot to display a plot group available from the model object.
For example, to display the plot group <pgtag> enter:
mphplot(model, <pgtag>);

This renders the graphics in a MATLAB figure window. In addition you can plot
results in a COMSOL Multiphysics Graphics window if you start COMSOL with
MATLAB using a graphics server. To do this for a plot group <pgtag> enter:
mphplot(model, <pgtag>, 'server', 'on');

See the COMSOL Installation Guide to start COMSOL with MATLAB

using a graphics server.
Another way to plot in a COMSOL Graphics window is to use the run method:
model.result(<pgtag>).run;

Mac OS does not support plotting in a COMSOL Graphics window.

The default settings for plotting in a MATLAB figure do not display the color legend.
To include the color legend in a figure, use the property rangenum:

ANALYZING THE RESULTS

107

mphplot(model, <pgtag>, 'rangenum', <idx>);

where the integer <idx> identifies the plot for which the color legend should be
displayed.
EXTRACT PLOT DATA

In some situation it can be useful to extract data from a plot, for example, if you need
to manually edit the plot as it is allowed in MATLAB. To get a cell array, dat, which
contains the data for each plot feature available in the plot group <pgtag> enter:
dat = mphplot(model, <pgtag>);
PLOT EXTERNAL DATA

Using the function mphplot you can also plot data that is specified directly as an input
argument. The supported data format is according to the structure provided by the
function mpheval. This allows you to plot data that has first been extracted from the
model then modified in MATLAB, on the model geometry. To plot the structure
<data>, run the command:
mphplot(<data>);

If the data structure contains the value of several expressions, set the one to display in
the plot with the index property:
mphplot(<data>, 'index', <idx>);

where <idx> is a positive integer that corresponds to the expression to plot.

mphplot supports only plotting of data structures that are of the type

point, line or surface evaluations from mpheval.

Using the colortable option to select from several available color tables when
visualizing data:
mphplot(<data>, 'colortable', colorname);

Obtain a list of alternatives for colorname from the on-line help by entering:
help colortable

To disable the mesh displayed together with the data results, set the property mesh to
off as in this command:
mphplot(<data>, 'mesh', 'off');

108 |

CHAPTER 3: BUILDING MODELS

EXAMPLE: PLOT MPHEVAL DATA

This example extracts COMSOL data at the MATLAB prompt, modifies it and plots
the data in a MATLAB figure.
First load the Busbar model from the COMSOL Multiphysics model library. Enter:
model = mphload('busbar');

To extract the temperature and the electric potential field, use the command mpheval:
dat = mpheval(model,{'T','V'},'selection',1);

To display the temperature field, using the thermal color table:

mphplot(dat,'index',1,'colortable','thermal');

Do a simple scaling of the electric potential then plot it using the default color table:
dat.d2 = dat.d2*1e-3;

Plot the newly evaluated data without the mesh:

mphplot(dat, 'index', 2, 'rangenum', 2, 'mesh', 'off');

ANALYZING THE RESULTS

109

To emphasize the geometry use the function mphgeom to display line plot on the dsame
figure:
hold on;
mphgeom(model, 'geom1', 'facemode', 'off')

The Data Set Syntax

Use Data Sets to make solutions and meshes available for visualization and data
analysis. You can create Solution Data Sets, Mesh Data Sets, or Visualization Data Sets
(such as, for instance, Cut Plane or Edge Data Sets). While Solution and Mesh Data

110 |

CHAPTER 3: BUILDING MODELS

Sets are self defined, Visualization Data Sets always refer to an existing Solution Data
Set.

See Data Sets in the section Commands Grouped by Function of the

COMSOL API Reference Manual to get a list of the available Data Sets.

All plots refer to data sets; the solutions are always available as the default
data set.
To create a data set at the MATLAB prompt, use the command:
model.result.dataset.create(<dsettag>, dsettype);

where dsettype is one of the available data set types.

Data Sets in the COMSOL Multiphysics Reference Manual

Use of Data Sets in the COMSOL API Reference Manual

The Numerical Node Syntax

Use the numerical node to perform numerical evaluation from within the COMSOL
Multiphysics model. Numerical operations such as computing averages, integrations,
maximums, or minimums of a given expression are available. You can also perform
point and global evaluations.
To create a numerical node, enter:
model.result.numerical.create(<numtag>, numtype);

where numtype is the type of operation to be performed by the node.

For a list of the syntax of the numerical results type available, see About
Results Commands in the COMSOL API Reference Manual.
To store the data needed to create a table and associate the table to the numerical node:
model.result.table.create(<tabletag>,'Table');

ANALYZING THE RESULTS

111

model.result.numerical(<numtag>).set('table',<tabletag>);

where <tabletag> is the tag of the table where you want to store the data evaluated
with the numerical operations defined with the tag <numtag>.
To extract the data stored in MATLAB into a table, use the methods getRealRow and
getImagRow, such as:
realRow = model.result.table(<tabletag>).getRealRow(<idx>);
imagRow = model.result.table(<tabletag>).getImagRow(<idx>);

where <idx> is the column index of the table <tabletag>.

For data evaluation in MATLAB you can also use the function mpheval,
mphevalpoint, mphglobal, mphint2, mphinterp, mphmax, mphmean and mphmin.

Extracting Results

Exporting Data
Use the export node to generate an animation or to export data to an external file
(ASCII format). This section includes information about Animation Export, Data
Export, and the Animation Player.
ANIMATION EXPORT

Animations can be defined as two different types: a movie or an image sequence. The
movie generates file formats such as GIF (.gif), AVI (.avi), or flash (.swf); the
image sequence generates a sequence of images. Make sure COMSOL with MATLAB
using a graphics server to enable plot on server.

To learn how to start COMSOL with MATLAB using a graphics server,

see the COMSOL Installation Guide.
To generate an animation, add an Animation node to the export method:
model.result.export.create(<animtag>, 'Animation');

To change the animation type use the 'type' property according to:
model.result.export(<animtag>).set('type', type);

112 |

CHAPTER 3: BUILDING MODELS

where type is either 'imageseq' or 'movie'.

To set the filename and finally create the animation, enter:
model.result.export(<animtag>).set(typefilename, <filenname>);
model.result.export(<animtag>).run;

In the above, typefilename depends on the type of animation export:

'imagefilename' for an image sequence, 'giffilename' for a gif animation,
'flashfilename' for a flash animation, and 'avifilename' for an avi animation.
For a movie type animation, it is possible to change the number of frames per second
with the command:
model.result.export(<animtag>).set('fps', <fps_number>);

where <fps_number> is a positive integer that corresponds to the number of frames

per second to use.
For all animation types you can modify the width and the height of the plot with the
set method:
model.result.export(<animtag>).set('width', <width_px>);
model.result.export(<animtag>).set('height', <height_px>);

where, the positive integers <width_px> and <height_px> are the width and height
size (in pixels), respectively, to use for the animation.
DATA EXPORT

In order to save data to an ASCII file, create a Data node to the export method:
model.result.export.create(<datatag>, 'Data');

Set the expression expr and the file name filenname, and run the export:
model.result.export.(<datatag>).setIndex('expr', <expr>, 0);
model.result.export.(<datatag>).set('filename', <filenname>);

Set the export data format with the struct property:

model.result.export.(<datatag>).set('struct', datastruct);

where datastruct can be set to 'spreadsheet' or 'sectionwise'.

See Data Formats in the COMSOL API Reference Manual for details
about the data formats used in the exported data files.
To export the data in the specified file, run the export node:

ANALYZING THE RESULTS

113

model.result.export.(<datatag>).run;
ANIMATION PLAYER

For transient and parametric studies, an animation player can be generated to create
interactive animations.
The player displays the figure on a COMSOL Graphics window. Make sure COMSOL
with MATLAB is started using a graphics server.

To learn how to start COMSOL with MATLAB using a graphics server,

see the COMSOL Installation Guide.
To create a player feature node to the model enter the command:
model.result.export.create(<playtag>, 'Player');

Then associate the player with an existing plot group by setting the plotgroup
property:
model.result.export(<playtag>).set('plotgroup', <pgtag>);

where <pgtag> refers to the plot group, which is animated in the player.
The default frame number used to generate the animation is 25, you can also specify
the number of frame with the command:
model.result.export(<playtag>).set('maxframe', <maxnum>);

where <maxnum> is a positive integer value that corresponds to the maximum number
of frames to generate with the player.
Use the run method to generate the player:
model.result.export(<playtag>).run;

114 |

CHAPTER 3: BUILDING MODELS

Working With Models

This section introduces you to the functionality available for LiveLink for
MATLAB including the wrapper functions and the MATLAB tools that can be

used and combined with a COMSOL Multiphysics model object.

In this chapter:
Using MATLAB Variables in Model Settings
Extracting Results
Running Models in a Loop
Running Models in Batch Mode
Working with Matrices
Extracting Solution Information and Solution Vectors
Retrieving Xmesh Information
Navigating the Model
Handling Errors and Warnings
Improving Performance for Large Models
Creating a Custom GUI
COMSOL 3.5a Compatibility

115

Using MATLAB Variables in Model

Settings
LiveLink for MATLAB allows you to define the model properties with MATLAB
variables or a MATLAB M-function.
In this section:
The Set and SetIndex Methods
Using a MATLAB Function to Define Model Properties

The Set and SetIndex Methods

You can use MATLAB variables to set properties of a COMSOL Multiphysics model.
Use the set or setIndex methods to pass the variable value from MATLAB to the
COMSOL model.
THE SET METHODS

Use the set method to assign parameter and/or property values. All assignments
return the parameter object, which means that assignment methods can be appended
to each other.
The basic method for assignment is:
something.set(name, <value>);

The name argument is a string with the name of the parameter/property. The
<value> argument can for example be a MATLAB integer or double array variable.
When using a MATLAB variable, make sure that the value corresponds to the model
unit system. COMSOL can also take care of the unit conversation automatically; in this
case convert the MATLAB integer/double variable to a string variable and use the set
method as:
something.set(property, [num2str(<value>)'[unit]']);

where is the unit you want to set the value property.

116 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

THE SETINDEX METHODS

Use the setIndex method to assign values to specific indices (0-based) in an array or
matrix property. All assignment methods return the parameter object, which means
that assignment methods can be appended to each other:
something.setIndex(name, <value>, <index>);

The name argument is a string with the name of the property, <value> is the value to
set the property, which can be a MATLAB variable value, and <index> is the index in
the property table.
When using a MATLAB variable make sure that the value corresponds to the model
unit system. COMSOL can automatically take care of the unit conversation; in this case
converting the MATLAB integer/double variable to a string variable and using the
set method as:
something.setIndex(name, [num2str(<value>)'[unit]'], <index>);

where [unit] is the unit you want to set the value property.

Using a MATLAB Function to Define Model Properties

Use MATLAB Function to define the model property. The function can either be
declared within the model object or called at the MATLAB prompt.
C A L L I N G M AT L A B F U N C T I O N S W I T H I N T H E C O M S O L M O D E L O B J E C T

LiveLink for MATLAB enables you to declare a MATLAB M-function directly from
within the COMSOL Multiphysics model object. This is typically the case if you want
to call a MATLAB M-function from the COMSOL Desktop. The function being
declared within the model object accepts any parameter, variable, or expression
arguments defined in the COMSOL model object. However, to use a variable defined
at the MATLAB prompt, the variable has to be transferred first in the COMSOL
model as a parameter, for example (see how to set a MATLAB variable in the
COMSOL model in The Set and SetIndex Methods).
The function is evaluated any time the model needs to be updated. The model object
cannot be called as an input argument of the M-function.

Calling MATLAB Functions

U S I N G M AT L A B V A R I A B L E S I N M O D E L S E T T I N G S

117

C A L L I N G M AT L A B F U N C T I O N S A T T H E M AT L A B P RO M P T

Use a MATLAB function to define a model property with the set method:
something.set(property, myfun(<arg>));

where myfun() is an M-function defined in MATLAB.

The function is called only when the command is executed at the MATLAB prompt.
The argument of the function <arg> called can be MATLAB variables. To include an
expression value from the model object, first extract it at the MATLAB prompt, as
described in Extracting Results.
The function myfun()accepts the model object model as an input argument as any
MATLAB variable.

118 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

Extracting Results
Use LiveLink for MATLAB to extract at the MATLAB prompt the data computed
in the COMSOL Multiphysics model. A suite of wrapper functions is available to
perform evaluation operations at the MATLAB prompt.
In this section:
Extracting Data From Tables
Extracting Data at Node Points
Extracting Data at Arbitrary Points
Evaluating an Expression at Geometry Vertices
Evaluating an Integral
Evaluating a Global Expression
Evaluating a Global Matrix
Evaluating a Maximum of Expression
Evaluating an Expression Average
Evaluating a Minimum of Expression
Evaluating Expressions on Particle Trajectories

Extracting Data From Tables

In the Table node you can store the data evaluated with the COMSOL Multiphysics
built-in evaluation method (see The Numerical Node Syntax).
Use mphtable to extract the data stored in the table with the tag <tbltag>. Enter:
tabl = mphtable(model,<tbltag>);

This creates a structure tabl made with the following fields:

headers for the table,
tag of the table,
data of the extracted table, and
filename when the table is exported to file.

EXTRACTING RESULTS

119

Extracting Data at Node Points

The function mpheval lets you evaluate expressions on node points. The function
output is available as a structure in the MATLAB workspace.
Call the function mpheval as in this command:
pd = mpheval(model, <expr>);

where <expr> is a string cell array that lists the COMSOL Multiphysics expression to
evaluate. The expression has to be defined in a COMSOL model object in order to be
evaluated.
pd is a structure with the following fields:

expr contains the list of names of the expressions evaluated with mpheval;
d1 contains the value of the expression evaluated. The columns in the data value
fields correspond to node point coordinates in columns in the field p. In case of
several expressions are evaluated in mpheval, additional field d2, d3,... are available;
p contains the node point coordinates information. The number of rows in p is the
number of space dimensions;
t contains the indices to columns in pd.p of a simplex mesh; each column in pd.t
represents a simplex;
ve contains the indices to mesh elements for each node points; and
unit contains the list of the unit for each evaluated expressions.
The rest of this section has additional information for the function mpheval:
Specify the Evaluation Data
Output Format
Specify the Evaluation Quality
Display the Expression in Figures
SPECIFY THE EVALUATION DATA

The function mpheval supports the following properties to set the data of the
evaluation to perform:
dataset, specify the solution data set to use in the evaluation:

120 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

pd = mpheval(model, <expr>, 'dataset', <dsettag>);

<dsettag> is the tag of a solution data set. The default value is the current solution

data set of the model. Selection data set such as Cut point, Cut line, Edge, Surface,
and so forth, are not supported.
selection, specify the domain selection for evaluation:
pd = mpheval(model, <expr>, 'selection', <seltag>);

where <seltag> is the tag of a selection node to use for the data evaluation.
<seltag> can also be a positive integer array that corresponds to the domain index
list. The default selection is all domains where the expression is defined. If the
evaluation point does not belong to the specified domain selection, the output value
is NaN.
edim, specify the element dimension for evaluation:
pd = mpheval(model, <expr>, 'edim', edim);

where edim is either a string or a positive integer such as: 'point' (0), 'edge' (1),
'boundary' (2), or 'domain' (3). The default settings correspond to the model
geometry space dimension. When using a lower space dimension value, make sure
that the evaluation point coordinates dimension has the same size.

Use the function mphevalpoint to evaluate expressions at geometric

points (see Evaluating an Expression at Geometry Vertices).
solnum, specify the inner solution number for data evaluation. Inner solutions are
generated for the following analysis types: time domain, frequency domain,
eigenvalue, or stationary with continuation parameters:
pd = mpheval(model, <expr>, 'solnum', <solnum>);

where <solnum> is an integer array corresponding to the inner solution index.

<solnum> can also be a string:'end' or 'all' to evaluate the expression for the last
inner solution, or all inner solution respectively. By default the evaluation is
performed on all inner solution.
outersolnum, specify the outer solution number for data evaluation. Outer
solutions are generated with parametric sweeps:
pd = mpheval(model, <expr>, 'outersolnum', <outersolnum>);

where <outersolnum> is a positive integer corresponding to the outer solution

index. <outersolnum> can also be a string, 'all' or 'end', to evaluate the

EXTRACTING RESULTS

121

expression for all or the last outer solution respectively. The default setting uses the
first outer solution for the data evaluation.
To evaluate the expression data at a specific time use the property t:
pd = mpheval(model, <expr>, 't', <time>);

where <time> is a double array. The default value corresponds to all the stored time
steps.
phase, specify the phase in degrees:
pd = mpheval(model, <expr>, 'phase', <phase>);

where <phase> is a double value.

pattern, use Gauss point evaluation:
pd = mpheval(model, <expr>, 'pattern','gauss');

The default evaluation is performed on the Lagrange points.

OUTPUT FORMAT

The function mpheval returns a structure in the MATLAB workspace. You can specify
other output data formats.
To only obtain the data evaluation as a double array, set the property dataonly to on:
pd = mpheval(model, <expr>, 'dataonly', 'on');

Include the imaginary part in the data evaluation with the property complexout:
pd = mpheval(model, <expr>, 'complexout', 'on');
SPECIFY THE EVALUATION QUALITY

Define mpheval function settings to specify the evaluation quality using these
properties:
refine, specify the element refinement for evaluation:
pd = mpheval(model, <expr>, 'refine', <refine>);

where <refine> is a positive integer. The default value is 1 which set the simplex
mesh identical to the geometric mesh.
smooth, specify the smoothing method to enforce continuity on discontinuous data
evaluation:
pd = mpheval(model, <expr>, 'smooth', smooth);

where smooth is either 'none', 'everywhere', or 'internal' (default). Set the

property to none to evaluate the data on elements independently, set to

122 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

everywhere to apply the smoothing to the entire geometry, and set to internal

to smooth the quantity inside the geometry (but no smoothing takes place across
borders between domains with different settings). The output with the same data
and same coordinates are automatically merged, which means that the output size
can differ depending on the smoothing method.
recover, specify the accurate derivative recovery:
pd = mpheval(model, <expr>, 'recover', recover);

where recover is either 'ppr', 'pprint', or 'off' (default). Set the property to
ppr to perform recovery inside domains or set to pprint to perform recovery inside
domains. Because the accurate derivative processing takes time, the property is
disabled by default.
OTHER EVALUATION PROPERTIES

To not use complex-value functions with real inputs, use the property complexfun:
pd = mpheval(model, <expr>, 'complexfun','off');

The default value uses complex-valued functions with real inputs.

Use the property matherr to return an error for undefined operations or expressions:
pd = mpheval(model, <expr>, 'matherr','on');
DISPLAY THE EXPRESSION IN FIGURES

You can display an expression evaluated with mpheval in an external figure with the
function mphplot (see Displaying The Results). The function mphplot only supports
a MATLAB structure provided by mpheval as input.

Extracting Data at Arbitrary Points

At the MATLAB prompt, the function mphinterp evaluates the result at arbitrary
points. To evaluate an expression at specific point coordinates, call the function
mphinterp as in the command:
[d1, ..., dn] = mphinterp(model,{'e1', ..., 'en'},'coord',<coord>);

where e1,...,en are the COMSOL Multiphysics expressions to evaluate, <coord> is

a NxM double array, with N the space dimension of the evaluation domain, and M is
the number of evaluation points. The output d1, ..., dn is a PxM double array,
where P is the length of the inner solution.
Alternatively, specify the evaluation coordinates using a selection data set:

EXTRACTING RESULTS

123

data = mphinterp(model, <expr>, 'dataset', <dsettag>);

where <dsettag> is a selection data set tag defined in the model, for example, Cut
point, Cut Plane, Revolve, and so forth.
The rest of this section has additional information for the function mphinterp:
Specify the Evaluation Data
Output Format
Specify the Evaluation Quality
Other Evaluation Properties
SPECIFY THE EVALUATION DATA

The function mphinterp supports the following properties to set the data of the
evaluation to perform:
dataset, specify the solution data set to use in the evaluation:
data =
mphinterp(model,<expr>,'coord',<coord>,'dataset',<dsettag>);
<dsettag> is the tag of a solution data set. The default value is the current solution

data set of the model.

selection, specify the domain selection for evaluation:
data =
mphinterp(model,<expr>,'coord',<coord>,'selection',<seltag>);

where <seltag> is the tag of a selection node to use for the data evaluation.
<seltag> can also be a positive integer array that corresponds to the domain index
list. The default selection is All domains where the expression is defined. If the
evaluation point does not belong to the specified domain selection the output value
is NaN.
edim, specify the element dimension for evaluation:
data = mphinterp(model,<expr>,'coord',<coord>,'edim',edim);

where edim is either a string or a positive integer such as 'point' (0), 'edge' (1),
'boundary' (2), or 'domain' (3). The default settings correspond to the model
geometry space dimension. When using a lower space dimension value, make sure
that the evaluation point coordinates dimension has the same size.
ext, specify extrapolation control value. This ensures you return data for points that
are outside the geometry:

124 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

data = mphinterp(model,<expr>,'coord',<coord>,'ext',<ext>);

where <ext> is a double value. The default value is 0.1.

solnum, specify the inner solution number for data evaluation. Inner solutions are
generated for the following analysis types: time domain, frequency domain,
eigenvalue, or stationary with continuation parameters:
data = mphinterp(model,<expr>,'coord',<coord>,solnum',<solnum>);

where <solnum> is an integer array corresponding to the inner solution index.

<solnum> can also be a string:'end' or 'all' to evaluate the expression for the last
inner solution, or all inner solution respectively. By default the evaluation is
performed on all inner solution.
outersolnum, specify the outer solution number for data evaluation. Outer
solutions are generated with parametric sweeps:
data = mphinterp(model,<expr>,'coord',<coord>,...
'outersolnum',<outersolnum>);

where <outersolnum> is a positive integer corresponding to the outer solution

index. <outersolnum> can also be a string, 'all' or 'end', to evaluate the
expression for all or the last outer solution respectively. The default settings use the
first outer solution for the data evaluation.
To evaluate the expression data at a specific time use the property t:
data = mphinterp(model,<expr>,'coord',<coord>,'t',<time>);

where <time> is a double array. The default value corresponds to all the stored time
steps.
phase, specify the phase in degrees:
data = mphinterp(model,<expr>,'coord',<coord>,'phase',<phase>);

where <phase> is a double value.

OUTPUT FORMAT

The function mphinterp returns in the MATLAB workspace a double array. It also
supports other output formats.
To evaluate several expressions at once, make sure that the same number of output
variables are defined as there are expressions specified:
[d1, ..., dn] = mphinterp(model,{'e1', ..., 'en'},'coord',<coord>);

To extract the unit of the evaluated expression, define an extra output variable:
[data, unit] = mphinterp(model,<expr>,'coord',<coord>);

EXTRACTING RESULTS

125

with unit is a 1xN cell array where N is the number of expressions to evaluate.
Include the imaginary part in the data evaluation with the property complexout:
data = mphinterp(model,<expr>,'coord',<coord>,'complexout','on');

To return an error if all evaluation points are outside the geometry, set the property
coorderr to on:
data = mphinterp(model,<expr>,'coord',<coord>,'coorderr','on');

By default the function returns the value NaN.

SPECIFY THE EVALUATION QUALITY

With the property recover, you can specify the accurate derivative recovery:
data = mphinterp(model,<expr>,'coord',<coord>,'recover', recover);

where recover is either 'ppr', 'pprint', or 'off' (the default). Set the property to
ppr to perform recovery inside domains or set to pprint to apply recovery to all
domain boundaries. Because the accurate derivative processing takes time, the
property is disabled by default.
OTHER EVALUATION PROPERTIES

Set the unit property to specify the unit of the evaluation:

data = mphinterp(model,<expr>,'coord',<coord>,'unit',<unit>);

where unit is a cell array with the same size as expr.

To not use complex-value functions with real inputs, use the property complexfun:
data = mphinterp(model,<expr>,'coord',<coord>,'complexfun','off');

The default value uses complex-value functions with real inputs.

Use the property matherr to return an error for undefined operations or expressions:
data = mphinterp(model,<expr>,'coord',<coord>,'matherr','on');

Evaluating an Expression at Geometry Vertices

The function mphevalpoint returns the result of a given expression evaluated at the
geometry vertices:
[d1,...,dn] = mphevalpoint(model,{'e1',...,'en'});

126 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

where e1,...,en are the COMSOL expressions to evaluate. The output d1, ..., dn
is a NxP double array, where N is the number of evaluation points and P the length of
the inner solution.
The rest of this section has additional information for the function mphevalpoint:
Specify the Evaluation Data
Output Format
SPECIFY THE EVALUATION DATA

The function mphevalpoint supports the following properties to set the data of the
evaluation to perform:
dataset, specify the solution data set to use in the evaluation:
data = mphevalpoint(model,<expr>,'dataset',<dsettag>);
<dsettag> is the tag of a solution data set. The default value is the current solution

data set of the model.

selection, specify the domain selection for evaluation:
data = mphevalpoint(model,<expr>,'selection',<seltag>);

where <seltag> is the tag of a selection node to use for the data evaluation.
<seltag> can also be a positive integer array that corresponds to the domain index
list. The default selection is all domains where the expression is defined. If the
evaluation point does not belong to the specified domain selection, the output value
is NaN.
solnum, specify the inner solution number for data evaluation. Inner solutions are
generated for the following analysis types: time domain, frequency domain,
eigenvalue, or stationary with continuation parameters:
data = mphevalpoint(model,<expr>,'solnum',<solnum>);

where <solnum> is an integer array corresponding to the inner solution index.

<solnum> can also be a string:'end' or 'all' to evaluate the expression for the last
inner solution, or all inner solution respectively. By default the evaluation is
performed on all inner solution.
outersolnum, specify the outer solution number for data evaluation. Outer
solutions are generated with parametric sweeps:
data = mphevalpoint(model,<expr>,'outersolnum',<outersolnum>);

where <outersolnum> is a positive integer corresponding to the outer solution

index. <outersolnum> can also be a string, 'all' or 'end', to evaluate the

EXTRACTING RESULTS

127

expression for all or the last outer solution respectively. The default settings use the
first outer solution for the data evaluation.
To evaluate the expression data at a specific time use the property t:
data = mphevalpoint(model,<expr>,'t', <time>);

where <time> is a double array. The default value corresponds to all the stored time
steps.
Perform a data series operation with the dataseries property:
data = mphevalpoint(model,<expr>,'dataseries', dataseries);

where dataseries is either 'mean', 'int', 'max', 'min', 'rms', 'std', or 'var'.
Depending on the property value, mphevalpoint performs the following
operationsmean, integral, maximum, minimum, root mean square, standard
deviation, or variance, respectively.
When performing a minimum or maximum operation on the data series, you can
specify to perform the operation using the real or the absolute value. Set the property
minmaxobj to 'real' or 'abs', respectively:
data = mphevalpoint(model,<expr>,'dataseries', dataseries,...
'minmaxobj', valuetype);

By default valuetype is 'real'.

OUTPUT FORMAT

The function mphevalpoint supports other output formats.

To extract the unit of the evaluated expression, define an extra output variable:
[data,unit] = mphevalpoint(model,<expr>);

with unit is a 1xN cell array where N is the number of expressions to evaluate.
By default, mphevalpoint returns the results as a squeezed singleton. To get the full
singleton set the squeeze property to off:
data = mphevalpoint(model,<expr>,'squeeze','off');

Set the property matrix to off to return the data as a cell array instead of a double
array:
data = mphevalpoint(model,<expr>,'matrix','off');

128 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

Evaluating an Integral
Evaluate an integral of expression with the function mphint2.
The function mphint is now obsolete and will be removed in a future
version of the software. If you are using this function in your code, you
can now replace it by mphint2.
To evaluate the integral of the expression over the domain with the highest space
domain dimension call the function mphint2 as in this command:
[d1,...,dn] = mphint2(model,'e1',...,'en'},edim);

where e1,...,en are the COMSOL Multiphysics expressions to integrate. The values
d1,...,dn are returned as a 1xP double array, with P the length of inner parameters.
edim is the integration dimension, which can be 'line', 'surface', 'volume', or
an integer value that specifies the space dimension (1, 2, or 3).
The rest of this section has additional information for the function mphint2:
Specify the Integration Data
Output Format
Specify the Integration Settings
SPECIFY THE INTEGRATION DATA

The function mphint2 supports the following properties to set the data of the
evaluation to perform:
dataset, specify the solution data set to use in the integration:
data = mphint2(model,<expr>,edim,'dataset',<dsettag>);
<dsettag> is the tag of a solution data set. The default value is the current solution

data set of the model.

selection, specify the integration domain:
data = mphint2(model,<expr>,edim,'selection',<seltag>);

where <seltag> is the tag of a selection node to use for the data evaluation.
<seltag> can also be a positive integer array that corresponds to the domain index
list. The default selection is all domains where the expression is defined. If the
evaluation point does not belong to the specified domain selection the output value
is NaN.

EXTRACTING RESULTS

129

 solnum, specify the inner solution number for data evaluation. Inner solutions are
generated for the following analysis types: time domain, frequency domain,
eigenvalue, or stationary with continuation parameters:
data = mphint2(model,<expr>,edim,'solnum',<solnum>);

where <solnum> is an integer array corresponding to the inner solution index.

<solnum> can also be a string:'end' or 'all' to evaluate the expression for the last
inner solution, or all inner solutions, respectively. By default the evaluation is
performed on all inner solutions.
outersolnum, specify the outer solution number for data evaluation. Outer
solutions are generated with parametric sweeps:
data = mphint2(model,<expr>,edim,'outersolnum',<outersolnum>);

where <outersolnum> is a positive integer corresponding to the outer solution

index. <outersolnum> can also be a string, 'all' or 'end', to evaluate the
expression for all or the last outer solution respectively. The default settings use the
first outer solution for the data evaluation.
To evaluate the expression data at a specific time use the property t:
data = mphint2(model,<expr>,edim,'t',<time>);

where <time> is a double array. The default value corresponds to all the stored time
steps.
OUTPUT FORMAT

The function mphint2 also supports other output formats.

To extract the unit of the evaluated expression, define an extra output variable:
[data,unit] = mphint2(model,<expr>,edim);

with unit is a 1xN cell array where N is the number of expressions to evaluate.
By default mphint2 returns the results as a squeezed singleton. To get the full
singleton, set the squeeze property to off:
data = mphint2(model,<expr>,edim,'squeeze','off');

Set the property matrix to off to return the data as a cell array instead of a double
array:
data = mphint2(model,<expr>,edim,'matrix','off');

130 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

SPECIFY THE INTEGRATION SETTINGS

To specify integration settings such as the integration method, integration order, or

axisymmetry assumption using these properties:
method, specify the integration method, which can be either integration or
summation:
data = mphint2(model,<expr>,edim,'method',method);

where method can be 'integration' or 'summation'. The default uses the

appropriate method for the given expression.
intorder, specify the integration order:
data = mphint2(model,<expr>,edim,'intorder',<order>);

where order is a positive integer. The default value is 4.

intsurface or intvolume, compute surface or volume integral for axisymmetry
models:
data = mphint2(model,<expr>,edim,'intsurface','on');
data = mphint2(model,<expr>,edim,'intvolume','on');

Evaluating a Global Expression

Evaluate a global expression with the function mphglobal.
To evaluate a global expression at the MATLAB prompt, call the function
mphglobal as in this command:
[d1,...,dn] = mphglobal(model,{'e1',...,'en'});

where e1,...,en are the COMSOL Multiphysics global expressions to evaluate. The
output values d1,...,dn are returned as a Px1 double array, with P the length of
inner parameters.
The rest of this section has additional information for the function mphglobal:
Specify the Evaluation Data
Output Format
Other Evaluation Properties
SPECIFY THE EVALUATION DATA

The function mphglobal supports the following properties to set the data of the
evaluation to perform:
dataset, specify the solution data set to use in the evaluation:

EXTRACTING RESULTS

131

data = mphglobal(model,<expr>,'dataset',<dsettag>);
<dsettag> is the tag of a solution data set. The default value is the current solution

data set of the model.

solnum, specify the inner solution number for data evaluation. Inner solutions are
generated for the following analysis types: time domain, frequency domain,
eigenvalue, or stationary with continuation parameters:
data = mphglobal(model,<expr>,'solnum',<solnum>);

where <solnum> is an integer array corresponding to the inner solution index.

<solnum> can also be a string:'end' or 'all' to evaluate the expression for the last
inner solution or all inner solutions, respectively. By default the evaluation is
performed on all inner solutions.
outersolnum, specify the outer solution number for data evaluation. Outer
solutions are generated with parametric sweeps:
data = mphglobal(model,<expr>,'outersolnum',<outersolnum>);

where <outersolnum> is a positive integer corresponding to the outer solution

index. <outersolnum> can also be a string, 'all' or 'end' to evaluate the
expression for all or the last outer solution, respectively. The default settings uses the
first outer solution for the data evaluation.
To evaluate the expression data at a specific time use the property t:
data = mphglobal(model,<expr>,'t',<time>);

where <time> is a double array. The default value corresponds to all the stored time
steps.
phase, specify the phase in degrees:
data = mphglobal(model,<expr>,'phase',<phase>);

where <phase> is a double value.

OUTPUT FORMAT

The function mphglobal also supports other output formats.

To extract the unit of the evaluated expression, define an extra output variable:
[data,unit] = mphglobal(model,<expr>);

with unit is a 1xN cell array where N is the number of expressions to evaluate.
Include the imaginary part in the data evaluation with the property complexout:
data = mphglobal(model,<expr>,'complexout','on');

132 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

OTHER EVALUATION PROPERTIES

Set the unit property to specify the unit of the evaluation:

data = mphglobal(model,<expr>,'unit',<unit>);

where <unit> is a cell array with the same length as <expr>.

Do not use complex-value functions with real inputs, use the property complexfun:
data = mphglobal(model,<expr>,'complexfun','off');

The default value uses complex-value functions with real inputs.

Use the property matherr to return an error for undefined operations or expressions:
data = mphglobal(model,<expr>,'matherr','on');

Evaluating a Global Matrix

mphevalglobalmatrix evaluates the matrix variable such as S-parameters in a model

with several ports activated as a parametric sweep and a frequency-domain study.

To evaluate the global matrix associated to the expression <expr>, enter the
command:
M = mphevalglobalmatrix(model,<expr>);

The output data M is a NxN double array, where N is the number of port boundary
condition set in the model.
SPECIFY THE EVALUATION DATA

Set the solution data set for evaluation with the property dataset:
data = mphevalglobalmatrix(model,<expr>,'dataset',<dsettag>);

where <dsettag> is the tag of a solution data.

Evaluating a Maximum of Expression

Use the function mphmax to evaluate the maximum of a given expression over an inner
solution list.
To evaluate the maximum of the COMSOL Multiphysics expressions e1,...,en use
the command mphmax:
[d1,...,dn] = mphmax(model,{'e1',...,'en'},edim);

EXTRACTING RESULTS

133

where edim is a string to define the element entity dimension: 'volume', 'surface',
or 'line'. edim can also be set as a positive integer value (3, 2, or 1 respectively). The
output variables d1,...,dn are an NxP array where N is the number of inner solutions
and P the number of outer solutions.
The rest of this section has additional information for the function mphmax:
Specify the Evaluation Data
Output Format
SPECIFY THE EVALUATION DATA

The function mphmax supports the following properties to set the data of the
evaluation to perform:
dataset, specify the solution data set to use in the evaluation:
data = mphmax(model,<expr>,edim,'dataset',<dsettag>);
<dsettag> is the tag of a solution data set. The default value is the current solution

data set of the model.

selection, specify the domain selection for evaluation:
data = mphmax(model,<expr>,edim,'selection',<seltag>);

where <seltag> is the tag of a selection node to use for the data evaluation.
<seltag> can also be a positive integer array that corresponds to the domain index
list. The default selection is all domains where the expression is defined. If the
evaluation point does not belong to the specified domain selection the output value
is NaN.
solnum, specify the inner solution number for data evaluation. Inner solutions are
generated for the following analysis types: time domain, frequency domain,
eigenvalue, or stationary with continuation parameters:
data = mphmax(model,<expr>,edim,'solnum',<solnum>);

where <solnum> is an integer array corresponding to the inner solution index.

<solnum> can also be a string:'end' or 'all' to evaluate the expression for the last
inner solution or all inner solutions, respectively. By default the evaluation is
performed on all inner solutions.
outersolnum, specify the outer solution number for data evaluation. Outer
solutions are generated with parametric sweeps:

134 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

data = mphmax(model,<expr>,edim,'outersolnum',<outersolnum>);

where <outersolnum> is a positive integer array corresponding to the outer

solution index. <outersolnum> can also be a string, 'all' or 'end', to evaluate
the expression for all or the last outer solution, respectively. The default setting uses
the first outer solution for the data evaluation.
To evaluate the expression data at a specific time use the property t:
data = mphmax(model,<expr>,edim,'t',<time>);

where <time> is a double array. The default value corresponds to all the stored time
steps.
OUTPUT FORMAT

The function mphmax also supports other output formats.

To extract the unit of the evaluated expression, define an extra output variable:
[data,unit] = mphmax(model,<expr>,edim);

where unit is a 1xN cell array and N is the number of expressions to evaluate.
By default mphmax returns the results as a squeezed singleton. To get the full singleton
set the squeeze property to off:
data = mphmax(model,<expr>,edim,'squeeze','off');

Set the property matrix to off to return the data as a cell array instead of a double
array:
data = mphmax(model,<expr>,edim,'matrix','off');

Evaluating an Expression Average

Use the function mphmean to evaluate the average of a given expression over inner
solution lists. To evaluate the mean of the COMSOL Multiphysics expressions
e1,...,en use the command mphmean:
[d1,...,dn] = mphmean(model,{'e1',...,'en'},edim);

where edim is a string to define the element entity dimension: 'volume', 'surface',
or 'line'. edim can also be set as a positive integer value (3, 2, or 1 respectively). The
output variables d1,...,dn are an NxP array where N is the number of inner solutions
and P the number of outer solutions.

EXTRACTING RESULTS

135

The rest of this section has additional information for the function mphmean:
Specify the Evaluation Data
Output Format
Specify the Integration Settings
SPECIFY THE EVALUATION DATA

The function mphmean supports the following properties to set the data of the
evaluation to perform:
dataset, specify the solution data set to use in the evaluation:
data = mphmean(model,<expr>,edim,'dataset',<dsettag>);
<dsettag> is the tag of a solution data set. The default value is the current solution

data set of the model.

selection, specify the domain selection for evaluation:
data = mphmean(model,<expr>,edim,'selection',<seltag>);

where <seltag> is the tag of a selection node to use for the data evaluation.
<seltag> can also be a positive integer array that corresponds to the domain index
list. The default selection is all domains where the expression is defined. If the
evaluation point does not belong to the specified domain selection the output value
is NaN.
solnum, specify the inner solution number for data evaluation. Inner solutions are
generated for the following analysis types: time domain, frequency domain,
eigenvalue, or stationary with continuation parameters:
data = mphmean(model,<expr>,edim,'solnum',<solnum>);

where <solnum> is an integer array corresponding to the inner solution index.

<solnum> can also be a string:'end' or 'all' to evaluate the expression for the last
inner solution or all inner solutions, respectively. By default the evaluation is
performed on all inner solutions.
outersolnum, specify the outer solution number for data evaluation. Outer
solutions are generated with parametric sweeps:
data = mphmean(model,<expr>,edim,'outersolnum',<outersolnum>);

where <outersolnum> is a positive integer array corresponding to the outer

solution index. <outersolnum> can also be a string, 'all' or 'end', to evaluate
the expression for all or the last outer solution, respectively. The default setting uses
the first outer solution for the data evaluation.

136 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

 To evaluate the expression data at a specific time use the property t:

data = mphmean(model,<expr>,edim,'t',<time>);

where <time> is a double array. The default value corresponds to all the stored time
steps.
OUTPUT FORMAT

The function mphmean also supports other output formats.

To extract the unit of the evaluated expression, define an extra output variable:
[data,unit] = mphmean(model,<expr>,edim);

where unit is a 1xN cell array and N is the number of expressions to evaluate.
By default mphmean returns the results as a squeezed singleton. To get the full
singleton set the squeeze property to off:
data = mphmean(model,<expr>,edim,'squeeze','off');

Set the property matrix to off to return the data as a cell array instead of a double
array:
data = mphmean(model,<expr>,edim,'matrix','off');
SPECIFY THE INTEGRATION SETTINGS

You can specify integration settings such as an integration method or integration order
to perform the mean operation. The available integration properties are:
method, specify the integration method, which can be either integration or
summation:
data = mphmean(model,<expr>,edim,'method',method);

where method can be 'integration' or 'summation'. The default uses the

appropriate method for the given expression.
intorder, specify the integration order:
data = mphmean(model,<expr>,edim,'intorder',<order>);

where <order> is a positive integer. The default value is 4.

Evaluating a Minimum of Expression

Use the function mphmin to evaluate the minimum of a given expression over an inner
solution list.

EXTRACTING RESULTS

137

To evaluate the minimum of the COMSOL expressions e1,...,en use the command
mphmin:
[d1,...,dn] = mphmin(model,{'e1',...,'en'},edim);

where edim is a string to define the element entity dimension: 'volume', 'surface',
or 'line'. edim can also be set as a positive integer value (3, 2, or 1 respectively). The
output variables d1,...,dn are an NxP array where N is the number of inner solutions
and P the number of outer solutions.
The rest of this section has additional information for the function mphmin:
Specify the Evaluation Data
Output Format
SPECIFY THE EVALUATION DATA

The function mphmin supports the following properties to set the data of the
evaluation to perform:
dataset, specify the solution data set to use in the evaluation:
data = mphmin(model,<expr>,edim,'dataset',<dsettag>);
<dsettag> is the tag of a solution data set. The default value is the current solution

data set of the model.

selection, specify the domain selection for evaluation:
data = mphmin(model,<expr>,edim,'selection',<seltag>);

where <seltag> is the tag of a selection node to use for the data evaluation.
<seltag> can also be a positive integer array that corresponds to the domain index
list. The default selection is all domains where the expression is defined. If the
evaluation point does not belong to the specified domain selection the output value
is NaN.
solnum, specify the inner solution number for data evaluation. Inner solutions are
generated for the following analysis types: time domain, frequency domain,
eigenvalue, or stationary with continuation parameters:
data = mphmin(model,<expr>,edim,'solnum',<solnum>);

where <solnum> is an integer array corresponding to the inner solution index.

<solnum> can also be a string:'end' or 'all' to evaluate the expression for the last
inner solution or all inner solutions, respectively. By default the evaluation is
performed on all inner solutions.

138 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

 outersolnum, specify the outer solution number for data evaluation. Outer
solutions are generated with parametric sweeps:
data = mphmin(model,<expr>,edim,'outersolnum',<outersolnum>);

where <outersolnum> is a positive integer array corresponding to the outer

solution index. <outersolnum> can also be a string, 'all' or 'end', to evaluate
the expression for all or the last outer solution, respectively. The default setting uses
the first outer solution for the data evaluation.
To evaluate the expression data at a specific time use the property t:
data = mphmin(model,<expr>,edim,'t',<time>);

where <time> is a double array. The default value corresponds to all the stored time
steps.
OUTPUT FORMAT

The function mphmin also supports other output formats.

To extract the unit of the evaluated expression, define an extra output variable:
[data,unit] = mphmin(model,<expr>,edim);

where unit is a 1xN cell array and N is the number of expressions to evaluate.
By default mphmin returns the results as a squeezed singleton. To get the full singleton
set the squeeze property to off:
data = mphmin(model,<expr>,edim,'squeeze','off');

Set the property matrix to off to return the data as a cell array instead of a double
array:
data = mphmin(model,<expr>,edim,'matrix','off');

Evaluating Expressions on Particle Trajectories

The function mphparticle only evaluates expressions using particle data

set generated with the Particle Tracing Module.
Evaluate expressions on particle trajectories with the function mphparticle. To
evaluate the particle position and the particle velocity run mphparticle as in this
command:
pd = mphparticle(model);

EXTRACTING RESULTS

139

pd is a structure containing the information about particle position and particle

velocity at every time step. The information is stored in the following fields:
p contains the coordinates of the particle position along the trajectories. The data
are stored in a NxMxL array where N is the number of time steps, M the number of
evaluation point along the particle trajectories, and L the evaluation space
dimension.
v contains the value of the particle velocity along the trajectories. The data are
stored in a NxMxL array where N is the number of time steps, M the number of
evaluation points along the particle trajectories, and L the evaluation space
dimension.
t contains the list of evaluation time.
You can also specify expressions to evaluate along the particle trajectories. Run the
function mphparticle as in this command:
pd = mphparticle(model,'expr','e1');

where 'e1' is the expression to evaluate along the particle trajectories. The output
structure pd contains the fields p, v, and t (described above) with the following ones:
unit contains the unit of the evaluated expression;
d1 contains the value of the expression. The data are stored in a NxM array where
N is the number of time steps and M the number of evaluation points along the
particle trajectories; and
expr contains the list of the evaluated expression.
Use a string cell array to evaluate several expressions at once. The result of the
evaluation is then stored in the field d1, d2, ..., dn corresponding to each evaluated
expression.
SPECIFY THE EVALUATION DATA

The function mphparticle supports the following properties to set the data of the
evaluation to perform:
dataset, specify the solution data set to use in the evaluation:
pd = mphparticle(model,'expr',<expr>,'dataset',<dsettag>);
<dsettag> is the tag of a particle solution data set. The default value is the current

particle solution data set of the model.

To evaluate the expression data at a specific time use the property t:

140 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

pd = mphparticle(model,'expr',<expr>,'t',<time>);

where <time> is a double array. The default value corresponds to all the stored time
steps.
OUTPUT FORMAT

The function mphparticle also supports other output formats.

Set the property dataonly to on to return only the data related to the specified
expression:
pd = mphparticle(model,'expr',<expr>,'dataonly','on');

The output structure pd only contains the field unit, d#, expr, and t (described
above).

EXTRACTING RESULTS

141

R unni ng M o de l s i n a Loop
A common use of LiveLink for MATLAB is to run models in a loop. MATLAB
provides several functionalities to run loops, including conditional statements and
error handling, and this section shows how to use that functionality together with the
COMSOL API syntax to run COMSOL Multiphysics models in loops.
In this section:
The Parametric Sweep Node
Running Model in a Loop Using the MATLAB Tools

The Parametric Sweep Node

Using the COMSOL API you can run models in loops. See Adding a Parametric
Sweep in the section Building Models.
By using the COMSOL built-in function to run models in loops, you can
ensure the model is saved automatically at each iteration. COMSOL also
offers tools to take advantage of clusters and distributed computer
architectures.

Running Model in a Loop Using the MATLAB Tools

Use MATLAB tools such as for or while statements to run your model in a loop.
The COMSOL API commands can be included in scripts using MATLAB commands.
To evaluate such a script you need to have MATLAB connected to a COMSOL server.
To run a model in a loop you do not need to run the entire M-files commands from
scratch. It is recommended to load a COMSOL model in MATLAB and run the loop
only over the desired operations. The COMSOL model is automatically updated when
running the study node.

142 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

You can run an M-file for a model from scratch if required, for example, to generate
the geometry in loop.
The model run inside a MATLAB loop is not automatically saved. Make
sure to save the model at each iteration using the command mphsave to
save the model object.
If you are not interested in saving the entire model object at each
iteration, you can extract data and store it in the MATLAB workspace.
See Extracting Results to find the most suitable function to your model.
When running loops in MATLAB, the iteration progress is taken care of by MATLAB;
only the COMSOL commands are executed in the COMSOL server.
You can generate as many nested loops as required and combine the loop with other
MATLAB conditional statements such as if and switch or error handling statements
such as try/catch. Or break the loop with break, or jump to the next loop iteration
with continue.

See the MATLAB help for more information about the MATLAB
commands for, while, if, switch, try/catch, break, and continue.

EXAMPLE: GEOMETRY PARAMETRIZATION

This example shows how to proceed to geometry parametrization using a MATLAB

for loop. The model consists of the busbar example available in the COMSOL
Multiphysics model library; see the Introduction to COMSOL Multiphysics.
In this example the loop iterates over the busbars width, wbb. The solution for each
parameter value is displayed using the second plot group defined in the COMSOL
model. All the results are plotted in the same figure:
model = mphload('busbar');
w = [5e-2 10e-2 15e-2 20e-2];
for i = 1:4
model.param.set('wbb',w(i));
model.study('std1').run;
subplot(2,2,i)
mphplot(model,'pg2','rangenum',1)
end

RUNNING MODELS IN A LOOP

143

The results from the computation display in these plots:

144 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

Running Models in Batch Mode

Use LiveLink for MATLAB to model in batch mode. At the MATLAB prompt you
can execute commands to set up the batch job using the COMSOL Multiphysics
built-in method or run custom scripts directly from a command line. In this section:
The Batch Node
Running an M-file in Batch Mode
Running an M-file in Batch Mode Without Display

The Batch Node

Using the COMSOL API you can run models in a loop. See Adding a Job Sequence.

Running an M-file in Batch Mode

Running COMSOL with MATLAB in batch mode requires that you
have xterm installed on your machine. If this is not the case see Running
an M-file in Batch Mode Without Display.
To run in batch an M-script that runs COMSOL Model is required. Start COMSOL
with MATLAB at a terminal window with this command:
comsol server matlab myscript

where myscript is the M-script, saved as myscript.m, that contains the operation to
run at the MATLAB prompt.
COMSOL Multiphysics does not automatically save the model. You need
to make sure that the model is saved before the end of the execution of
the script. See Loading and Saving a Model.
You can also run the script in batch without the MATLAB desktop and the MATLAB
splash screen. Enter this command:
comsol server matlab myscript -nodesktop -mlnosplash

RUNNING MODELS IN BATCH MODE

145

Running an M-file in Batch Mode Without Display

To connect COMSOL with a MATLAB terminal requires that xterm is installed on
the machine. If this is not the case as it might be for a computation server, a
workaround is to connect manually MATLAB to a COMSOL server with the function
mphstart.
These steps describe how to run an M-script that runs a COMSOL model:
1 In a system terminal prompt start a COMSOL server with the command:
comsol server &

2 In the same terminal window change the path to the COMSOL installation

directory:
cd COMSOL_path/mli

3 From that location, start MATLAB without display and run the mphstart function

in order to connect MATLAB to COMSOL:

matlab -nodesktop -mlnosplash -r "mphstart; myscript"

For more information about how to connect MATLAB to a COMSOL server see
Starting COMSOL with MATLAB on Windows / Mac OSX / Linux.

146 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

Working with Matrices

In this section:
Extracting System Matrices
Set System Matrices in the Model
Extracting State-Space Matrices

Extracting System Matrices

Extract the matrices of the COMSOL Multiphysics linearized system with the function
mphmatrix. To call the function mphmatrix, specify a solver node and the list of the
system matrices to extract:
str = mphmatrix(model, <soltag>, 'out', out);

where <soltag> is the solver node tag used to assemble the system matrices and out
is a cell array containing the list of the matrices to evaluate. The output data str
returned by mphmatrix is a MATLAB structure, and the fields correspond to the
assembled system matrices.
The system matrices that can be extracted with mphmatrix are listed in the table:
EXPRESSION

DESCRIPTION

Stiffness matrix

Load vector

Constraint vector

Constraint Jacobian

Damping matrix

Mass matrix

NF

Constraint force Jacobian

NP

Optimization constraint Jacobian (*)

MP

Optimization constraint vector (*)

MLB

Lower bound constraint vector (*)

MUB

Upper bound constraint vector (*)

Kc

Eliminated stiffness matrix

Lc

Eliminated load vector

WO R K I N G W I T H M A T R I C E S

147

EXPRESSION

DESCRIPTION

Dc

Eliminated damping matrix

Ec

Eliminated mass matrix

Null

Constraint null-space basis

Nullf

Constraint force null-space matrix

ud

Particular solution ud

uscale

Scale vector

(*) Requires the Optimization Module.

SEL ECT IN G LINEAR IZ ATION PO INT S

The default selection of linearization points for the system matrix assembly is the
current solution of the solver node associated to the assembly.
If the linearization point is not specified when calling mphmatrix,
COMSOL automatically runs the entire solver configuration before
assembling and extracting the matrices.
Save time during the evaluation by manually setting the linearization point. Use the
initmethod property as in this command:
str = mphmatrix(model, <soltag>, 'out', out, 'initmethod', method);

where method corresponds to the type of linearization pointthe initial value

expression ('init') or a solution ('sol').
To set the solution to use for the linearization point, use the property initsol:
str = mphmatrix(model, <soltag>, 'out', out, 'initsol',
<initsoltag>);

where <initsoltag> is the solver tag to use for linearization points. You can also set
the initsol property to 'zero', which corresponds to using a null solution vector as a
linearization point. The default is the current solver node where the assemble node is
associated.
For continuation, time-dependent, or eigenvalue analyses you can set the solution
number to use as a linearization point. Use the solnum property:
str = mphmatrix(model, <soltag>, 'out', out, 'solnum', <solnum>);

where <solnum> is an integer value corresponding to the solution number. The default
value is the last solution number available with the current solver configuration.

148 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

See Retrieving Xmesh Information to learn how to get relation between

the degrees of freedom information in the matrix system and coordinates
or element information.
EXAMPLE: MPHMATRIX

The following illustrates how to use the mphmatrix command to extract eliminated
system matrices of a stationary analysis and linear matrix system at the MATLAB
prompt.
The model consists of a linear heat transfer problem solved on a unit square with a 1e5
W/m^2 surface heat source and temperature constraint. Only one quarter of the

geometry is represented in the model. For simplification reasons, the mesh is made of
four quad elements.
These commands set the COMSOL model object:
model = ModelUtil.create('Model');
geom1 = model.geom.create('geom1', 2);
geom1.feature.create('sq1', 'Square');
geom1.run;
mat1 = model.material.create('mat1');
def = mat1.materialModel('def');
def.set('thermalconductivity',{'4e2'});
ht = model.physics.create('ht', 'HeatTransfer', 'geom1');
hs1 = ht.feature.create('hs1','HeatSource',2);
hs1.selection.set(1);
hs1.set('Q',1,'1e5');
temp1 = ht.feature.create('temp1','TemperatureBoundary',1);
temp1.selection.set([1 2]);
mesh1 = model.mesh.create('mesh1','geom1');
dis1 = mesh1.feature.create('dis1','Distribution');
dis1.selection.set([1 2]);
dis1.set('numelem','2');
mesh1.feature.create('map1','Map');
std1 = model.study.create('std1');
std1.feature.create('stat','Stationary');
std1.run;

WO R K I N G W I T H M A T R I C E S

149

To extract the solution vector of the computed solution, run the function mphgetu as
in this command:
U = mphgetu(model);

To assemble and extract the eliminated stiffness matrix and the eliminated load vector,
set the linearization point to the initial value expression by entering:
MA = mphmatrix(model ,'sol1', ...
'Out', {'Kc','Lc','Null','ud','uscale'},...
'initmethod','sol','initsol','zero');

Solve for the eliminated solution vector using the extracted eliminated system:
Uc = MA.Null*(MA.Kc\MA.Lc);

Combine the eliminated solution vector and the particular vector:

U0 = Uc+MA.ud;

Scale back the solution vector:

U1 = (1+U0).*MA.uscale;

Now compare both solution vector U and U1 computed by COMSOL and by the
matrix operation, respectively.

Set System Matrices in the Model

Use the function mphinputmatrix to set a linear matrix system to a model:
mphinputmatrix(model,<str>,<soltag>,<soltypetag>)

This command set the matrices of a linear system stored in the MATLAB structure
<str> into the model. The linear system is associated to the solver sequence <soltag>
and is to be solved by the solver <soltypetag>.
mphinputmatrix only supports the solver types Stationary, Eigenvalue, and Time.

A valid structure <str> for a stationary solver includes the following fields:

150 |

FIELD

DESCRIPTION

Stiffness matrix

Load vector

Constraint vector

Constraint Jacobian

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

A valid structure <str> for a time-dependent or an eigenvalue solver includes the

following fields:
EXPRESSION

DESCRIPTION

Stiffness matrix

Load vector

Constraint vector

Constraint Jacobian

Damping matrix

Mass matrix

You can also include the Constraint force Jacobian vector, defined in the field NF.
Once the linear system is loaded in the model, you can directly run the solver.

The system matrices are not stored in the model once it is saved in the
MPH-format or loaded to the COMSOL Desktop.

EXAMPLE: SET A MODEL WITH A MODIFIED MATRIX SYSTEM

This example deals with heat transfer in solids physics. The geometry and physics
settings are already set in the model and saved in the MPH-format. The Model
MPH-file comes with the COMSOL installation.
At the MATLAB prompt you load the model and add an additional line heat source to
the model directly in the system matrix by manually changing the load vector. Then
compute the solution of the modified system in COMSOL.
Load the base Model MPH-file and display the geometry:
model = mphload('model_tutorial_llmatlab.mph');
mphgeom(model)

WO R K I N G W I T H M A T R I C E S

151

This results in the following MATLAB figure:

Draw the line to be used as a line heat source in the model and plot the modified
geometry:
b1 = model.geom('geom1').feature.create('b1', 'BezierPolygon');
b1.set('p', {'1e-2' '5e-2'; '1e-2' '5e-2'; '1e-2' '1e-2'});
mphgeom(model,'geom1','edgelabels','on','facealpha',0.5);

In the figure below you can see that the added line as the index 21:

Generate a mesh with finer mesh settings:

mesh1 = model.mesh('mesh1');
mesh1.feature.create('ftet1', 'FreeTet');
mesh1.feature('size').set('hauto', '3');
mesh1.run;
mphmesh(model)

152 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

Set the solver sequence associated to a stationary study node:

std1 = model.study.create('std1');
std1.feature.create('stat', 'Stationary');
sol1 = model.sol.create('sol1');
sol1.study('std1');
st1 = sol1.feature.create('st1', 'StudyStep');
st1.set('studystep', 'stat');
v1 = sol1.feature.create('v1', 'Variables');
v1.set('control', 'stat');
sol1.feature.create('s1', 'Stationary');

Set the dependent variable discretization with linear shape function:

Shape = model.physics('ht').prop('ShapeProperty');
Shape.set('order_temperature', 1, '1');

The heat transfer physics interface automatically compute for internal DOFs in order
to evaluate fluxes accurately at the boundaries. Deactivate the internal DOFs with the
command:
Shape.set('boundaryFlux_temperature', 1, '0');

Now extract the matrices of the linear system associated to the solver sequence sol1:
ME = mphmatrix(model,'sol1','Out',{'K' 'L' 'M' 'N'},...
'initmethod','sol','initsol','zero');

To retrieve the degrees of freedom that belong to edge 21, you need to get the
geometric mesh data:
[stats,data] = mphmeshstats(model);

With the mesh data structure data, you can get the element indices that belong to
edge 2. Use the MATLAB find function to list all the indices:

WO R K I N G W I T H M A T R I C E S

153

elem_idx = find(data.elementity{1}==21)'

With the function mphxmeshinfo, retrieve the finite element mesh information
associated to solver sequence sol1:
info = mphxmeshinfo(model,'soltag','sol1','studysteptag','v1');

In the info structure you can get the DOFs indices that belong to the edge element
defined with the indices elem_idx:
edgdofs_idx = [];
for i = 1:length(elem_idx)
edgdofs_idx = [edgdofs_idx;
info.elements.edg.dofs(:,elem_idx(i))];
end
edgdofs_idx might contain duplicate DOFs indices. This is because the information
is from the element level; the duplicate indices correspond to the connecting node
between two adjacent elements.

First remove the duplicate entities:

unique_idx

= unique(edgdofs_idx);

Edit the load vector for the DOF that belong to edge 21, the total applied power is
50 W:
ME.L(unique_idx+1) = 50/length(unique_idx);

Now that the linear system has been modified, set it back in the model:
mphinputmatrix(model,ME,'sol1','s1')

Compute the solution of the added system:

model.sol('sol1').runAll;

Display the solution:

pg1 = model.result.create('pg1', 'PlotGroup3D');
pg1.feature.create('surf1', 'Surface');

154 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

mphplot(model,'pg1','rangenum',1)

Extracting State-Space Matrices

Use state-space export to create a linearized state-space model corresponding to a
COMSOL Multiphysics model. You can export the matrices of the state-space form
directly to the MATLAB workspace with the command mphstate.
This section includes information about The State-Space System, how to Extract
State-Space Matrices and Set Linearization Points and has an Example: Extracting
State-Space Matrices.
THE STATE-SPACE SYSTEM

A state-space system is the mathematical representation of a physical model. The

system consistent in an ODE linking input, output, and state-space variable. A dynamic
system can be represented with the following system:
dx
------- = Ax + Bu
dt
y = Cx + Du

An alternative representation of the dynamic system is:

Mcx = McAx + McBu

y = Cx + Du
This form is more suitable for large systems because the matrices MC and MA usually
become much more sparse than A.

WO R K I N G W I T H M A T R I C E S

155

If the mass matrix MC is small, it is possible to approximate the dynamic state-space

model with a static model, where MC= 0:
1

y = D C McA McB u
Let Null be the PDE constraint null-space matrix and ud a particular solution fulfilling
the constraints. The solution vector U for the PDE problem can then be written
U =

Null x

+ ud + u0

where u0 is the linearization point, which is the solution stored in the sequence once
the state-space export feature is run.
EXTRACT STATE-SPACE MATRICES

The function mphstate requires that the input variables, output variables, and the list
of the matrices to extract in the MATLAB workspace are all defined:
str = mphstate(model, <soltag>, 'input', <input>, ...
'output', <output>, 'out', out);

where <soltag> is the solver node tag used to assemble the system matrices listed in
the cell array out, and <input> and <output> are cell arrays containing the list of the
input and output variables, respectively.
The output data str returned by mphstate is a MATLAB structure and the fields
correspond to the assembled system matrices.
The input variables need to be defined as parameters in the COMSOL model. The
output variables are defined as domain point probes or global probes in the COMSOL
model.
The system matrices that can be extracted with mphstate are listed in the table:

156 |

EXPRESSION

DESCRIPTION

MA

McA matrix

MB

McB matrix

A matrix

B matrix

C matrix

D matrix

Mc

Mc matrix

Null

Null matrix

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

EXPRESSION

DESCRIPTION

ud

ud vector

x0

x0 vector

To extract sparse matrices set the property sparse to on:

str = mphstate(model, <soltag>, 'input', <input>, ...
'output', <output>, 'out', out, 'sparse', 'on');

To keep the state-space feature node, set the property keepfeature to on:
str = mphstate(model, <soltag>, 'input', <input>, ...
'output', <output>, 'out', out, 'keepfeature', 'on');
SET LINEARIZATION POINTS
mphstate uses linearization points to assemble the state-space matrices. The default

linearization point is the current solution provided by the solver node, to which the
state-space feature node is associated. If there is no solver associated to the solver
configuration, a null solution vector is used as a linearization point.

The linearization point needs to be a steady-state solution.

You can manually select the linearization point to use. Use the initmethod property
to select a linearization point:
str = mphstate(model, <soltag>, 'input', <input>, ...
'output', <output>, 'out', out, 'initmethod', method);

where method corresponds to the type of linearization pointthe initial value

expression ('init') or a solution ('sol').
To set the solution to use for the linearization point, use the property initsol:
str = mphstate(model, <soltag>, 'input', <input>, ...
'output', <output>, 'out', out, 'initsol', <initsoltag>);

where <initsoltag> is the solver tag to use for a linearization point. You can also set
the initsol property to 'zero', which corresponds to using a null solution vector as a
linearization point. The default is the current solver node where the assemble node is
associated.
For continuation, time-dependent, or eigenvalue analyses you can set which solution
number to use as a linearization point. Use the solnum property:

WO R K I N G W I T H M A T R I C E S

157

str = mphstate(model, <soltag>, 'input', <input>, ...

'output', <output>, 'out', out, 'solnum', <solnum>);

where <solnum> is an integer value corresponding to the solution number. The default
value is the last solution number available with the current solver configuration.
EXAMPLE: EXTRACTING STATE-SPACE MATRICES

To illustrate how to use the mphstate function to extract the state-space matrices of
the model heat_transient_axi from the COMSOL Multiphysics model library. To be
able to extract the state-space matrices you need to modify an existing model. First,
create a parameter T0 that is set as the external temperature:
model = mphload('heat_transient_axi');
model.param.set('Tinput','1000[degC]');
model.physics('ht').feature('temp1').set('T0', 1, 'Tinput');

Then create a domain point probe:

pdom1 = model.probe.create('pdom1', 'DomainPoint');
pdom1.model('comp1');
pdom1.setIndex('coords2','0.2',0,0);
pdom1.setIndex('coords2','0.3',0,1);

Change the time stepping:

time = model.study('std1').feature('time');
time.set('tlist','range(0,50,2e3)');

Extract the matrices of the state-space system using Tinput as an input variable and
the probe comp1.ppb1 as an output variable:
M = mphstate(model,'sol1','out',{'Mc' 'MA' 'MB' 'C' 'D' 'x0'},...
'input','Tinput', 'output', 'comp1.ppb1');

Compute the state-space system with the extracted matrices:

u = 1;
T0= 1273.15;
opt = odeset('mass', M.Mc);
func = @(t,x) M.MA*x + M.MB*u;
[t,x] = ode23s(func, [0:50:2e3], M.x0, opt);
y = M.C*x'+M.D*u+T0;

Compare the solution computed with the system and the one computed with
COMSOL Multiphysics (see Figure 4-1):
plot(t,y)
hold on
Tnum = mphinterp(model,'T','coord',[0.2;0.3],'t',t);

158 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

plot(t,Tnum,'r+')

Figure 4-1: Temperature distribution computed with the state-space system (blue line) and
COMSOL Multiphysics (red marker).

WO R K I N G W I T H M A T R I C E S

159

Extracting Solution Information and

Solution Vectors
In this section:
Obtaining Solution Information
Retrieving Solution Information and Solution Data Sets Based on Parameter Values
Extracting Solution Vector

Obtaining Solution Information

Get the solution object information with the function mphsolinfo. Specify only the
model object to obtain the information of the default solution object:
info = mphsolinfo(model)

This section includes information about Specifying the Solution Object and the
Output Format.
The function mphsolinfo replaces the function mphgetp. If you are
using the later you can now replace it as it will be removed in a future
version.
SPECIFYING THE SOLUTION OBJECT

To retrieve the information of a specific solution object, set the soltag property with
the solver tag soltag associated to the solution object:
info = mphsolinfo(model, 'soltag', <soltag>);

If there are several solution data sets attached to the solver, for example, solution data
sets with different selections, specify the data set to use to get the solution object
information with the dataset property:
info = mphsolinfo(model, 'dataset', <dsettag>);

where dsettag the tag of the solution data set to use.

160 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

OUTPUT FORMAT

The output info is a MATLAB structure. The default fields available in the structure
are listed in the table:
FIELDS

DESCRIPTION

soltag

Tag of the solver associated to the solution object

study

Tag of the study associated to the solution object

size

Size of the solution vector

nummesh

Number of mesh in the solution (for automatic remeshing)

sizes

Size of solution vector and inner parameters for each mesh

soltype

Solver type

solpar

Parameter name

sizesolvals

Length of parameter list

solvals

Inner parameter value

paramsweepnames

Outer parameter name

paramsweepvals

Outer parameter value

batch

Batch information

dataset

Tag of the solution data set associated to the solution object

To get the information about the number of solutions, set the property nu to on:
info = mphsolinfo(model, 'nu', 'on');

The info structure is added with the following fields:

FIELDS

DESCRIPTION

NUsol

Number of solutions vectors stored

NUreacf

Number of reaction forces vectors stored

NUadj

Number of adjacency vectors stored

NUfsens

Number of functional sensitivity vectors stored

NUsens

Number of forward sensitivity vectors stored

The batch field is a a structure including the following fields:

BATCH FIELDS

DESCRIPTION

type

The type of batch

psol

Tag of the associated solver node

E X T R A C T I N G S O L U T I O N I N F O R M A T I O N A N D S O L U T I O N VE C T O R S

161

BATCH FIELDS

DESCRIPTION

sol

Tag of the stored solution associated to psol

seq

Tag of the solver sequence associated to psol

Retrieving Solution Information and Solution Data Sets Based on

Parameter Values
A model can contain several solution vectors computed with different values of
parameters, such as time, eigenvalue, or model parameters. These solution vectors can
be available in different solution data sets. Use the function mphsolutioninfo to
retrieve the solution vector corresponding to a specified study parameter value.
The parameters used in a study can be group in two distinct solution number types:
The inner solution, containing the solution computed with parameters such as
eigenvalues, time steps, or continuation parameter combinations.
The outer solution, containing the solution computed with parameters defined in
parametric sweep.
To get information about all solution object and solution data set combinations in the
model enter the command:
info = mphsolutioninfo(model)

The output info is a structure containing these fields:

FIELDS

DESCRIPTION

solutions

List of the solution object tags available in the model

sol#

Substructure containing information related to the solution

number #

The substructure info.sol# has these fields:

162 |

FIELDS

DESCRIPTION

dataset

List of the tags of the dataset associated to the solution

study

Tag of the study that computed the solution

sequencetype

Type of solution node

cellmap

Connections between parameters and inner/outer solution

numbers; the field is not available by default.

values

Values of the parameters used in the solution

parameters

Names of the parameters used in the solution

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

FIELDS

DESCRIPTION

mapheaders

Headers of the table stored in the map field

map

Connections between the parameter values and the solution

number (inner and outer solutions)

You can also retrieve the solution objects and solution data sets related to a specific
parameter value with the command:
info = mphsolutioninfo(model,'parameters',{'e1','v1','tol1'});

where e1 is the expression name, v1 the value of the expression.

The property parameters can also be set as a 1xN cell array where N corresponds to the
number of parameters to specify.
This section includes information about Specifying the Solution Object and the
Output Format. It also includes the section, Example: Retrieving Solution
Information.
SPECIFYING THE SOLUTION OBJECT

To retrieve the information of a specific solution object, set the soltag property with
the solver tag soltag associated to the solution object:
info = mphsolutioninfo(model, 'soltag', <soltag>);

If there are several solution data sets attached to the solver, for example, solution data
sets with different selections, specify the data set to use to get the solution object
information with the dataset property:
info = mphsolutioninfo(model, 'dataset', <dsettag>);

where dsettag the tag of the solution data set to use.

OUTPUT FORMAT

To include the cellmap field in the info.sol# substructure set the property cellmap
to on:
info = mphsolutioninfo(model, 'cellmap', 'on');

Improve the visibility of the map table by sorting the row using either the column
number or the name in the map header:
info = mphsolutioninfo(model, 'sort', <idx>);

where <idx> is a positive integer equal to the column number or a string

corresponding to the name of the column header.

E X T R A C T I N G S O L U T I O N I N F O R M A T I O N A N D S O L U T I O N VE C T O R S

163

EXAMPLE: RETRIEVING SOLUTION INFORMATION

This example shows how to use the function mphsolutioninfo to retrieve solution
information in a mode combining a parametric sweep and transient analysis.
Start by loading the base model model_tutorial_llmatlab from the COMSOL
Multiphysics model library; this model contains base settings for a thermal analysis:
model = mphload('model_tutorial_llmatlab');

Now create a study combining a parametric sweep and a transient study step. The
parametric sweep consist by varying the parameters that set the heat source and the
bottom temperature. This is done with these commands:
std = model.study.create('std');
param = std.feature.create('param', 'Parametric');
param.setIndex('pname', 'power', 0);
param.setIndex('plistarr', '30 60 90',0);
param.setIndex('pname', 'Temp', 1);
param.setIndex('plistarr', '300 320', 1);
time = std.feature.create('time', 'Transient');
time.set('tlist', 'range(0,1,25)');

Set the sweep type to generate all possible combinations of the parameters power and
tf and compute the study:
param.set('sweeptype', 'filled');
std.run;

Once the solution is computed (it takes about 90 seconds), you can retrieve the
solution information in the model:
info = mphsolutioninfo(model)

The output info is a structure containing nine fields. By navigating in the info
structure you can retrieve how the solutions are stored in the model.
info.sol1 contains the solution information related to the solver sequence sol1.
The associated dataset is dset1.
info.sol2 contains the solution information for the parametric sequence. This
regroups the solution vectors computed for all outer parameters.
The other substructures contain the solution information for all possible outer solution
combinations.
Get the relation between the parameter values and the inner and outer solution
numbers:
map = info.sol2.map

164 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

Retrieve the solution information related to the parameters power = 60 W:

info = mphsolutioninfo(model, 'parameters', {'power',60,0})

Retrieve the solution information related to the parameters power = 60 W,

Temp = 300 K and t = 10.4 seconds, for the time use a tolerance of 0.5 seconds to find
the appropriate inner solution number:
info = mphsolutioninfo(model, 'parameters', {{'power',60,0},...
{'Temp',300,0},{'t',10.4,0.5}})

To get the list of the solutions that contain the given parameters enter:
solnum = info.solutions

Extracting Solution Vector

To extract the solution vector with the function mphgetu, enter:
U = mphgetu(model);

where U is an Nx1 double array, with N the number of degrees of freedom of the
COMSOL Multiphysics model.
This section includes information about Specifying the Solution and the Output
Format.
You can refer to the function mphxmeshinfo to receive the DOF name or
the node coordinates in the solution vector, see Retrieving Xmesh
Information.
SPECIFYING THE SOLUTION

Change the solver node to extract the solution vector with the property solname:
U = mphgetu(model, 'soltag', <soltag>);

where <soltag> is the tag of the solver node.

For solver settings that compute for several inner solutions, select the inner solution to
use with the solnum property:
U = mphgetu(model, 'solnum', <solnum>);

where <solnum> a positive integer vector that corresponds to the solution number to
use to extract the solution vector. For time-dependent and continuation analyses, the

E X T R A C T I N G S O L U T I O N I N F O R M A T I O N A N D S O L U T I O N VE C T O R S

165

default value for the solnum property is the last solution number. For an eigenvalue
analysis, it is the first solution number.
A model can contain different types of solution vectorsthe solution of the problem,
the reaction forces vector, the adjoint solution vector, the functional sensitivity vector,
or the forward sensitivity. In mphgetu, you can specify the type of solution vector to
extract with the type property:
U = mphgetu(model, 'type', type);

where type is one of these strings 'sol', 'reacf', 'adj', or 'sens' used to extract the
solution vector, the reaction forces, the functional sensitivity, or the forward sensitivity,
respectively.
OUTPUT FORMAT
mphgetu returns the default the solution vector. Get the time derivative of the solution

vector Udot by adding a second output variable:

[U, Udot] = mphgetu(model);

In case the property solnum is set as a 1x M array and the solver node only uses one
mesh to create the solution, the default output is an NxM array, where N is the number
of degrees of freedom of the model. Otherwise, the output U is a cell array that contains
each solution vector. If you prefer to have the output in a cell array format, set the
property matrix to off:
U = mphgetu(model, 'solnum', <solnum>, 'matrix', 'off');

166 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

Retrieving Xmesh Information

Use LiveLink for MATLAB to retrieve information of the COMSOL Multiphysics
finite element model at the MATLAB workspace low level.
In this section:
The Extended Mesh (Xmesh)
Extracting Xmesh Information

The Extended Mesh (Xmesh)

The extended mesh (xmesh) is the finite element mesh used to compute the solution.
This contains the information about elements, nodes, and degrees of freedom such as
DOF names, position of the nodes in the assembled matrix system, or how elements
and nodes are connected.

Extracting Xmesh Information

The function mphxmeshinfo returns the extended mesh information. To get the
xmesh information of the current solver and mesh node, enter the command:
info = mphxmeshinfo(model);

where info is a MATLAB structure that contains the fields in the table:
FIELDS

DESCRIPTION

soltag

Tag of the solver node

ndofs

Number of degrees of freedom

fieldnames

List of field variables names

fieldndofs

Number of degrees of freedom for each field variable

meshtypes

List of the mesh type

geoms

Tag of the geometry node used in the model

dofs

Structure containing the dofs information

nodes

Structure containing the nodes information

elements

Structure containing the elements information

RETRIEVING XMESH INFORMATION

167

The dofs substructure contains the fields listed in the table:

FIELDS

DESCRIPTION

geomnums

Index of the geometry tag for each dofs

coords

Coordinates of the dofs

nodes

Nodes index of the dofs

dofnames

Variable names

nameinds

Variable names index of the dofs

The nodes substructure contains the fields listed in the table:

FIELDS

DESCRIPTION

coords

Nodes coordinates

dofnames

Variable names

dofs

NxM array containing the index (0-based) of the dofs for each
node. N being the length of dofnames and M the number of nodes

The element substructure contains the fields listed in the table:

FIELDS

DESCRIPTION

meshtypes

List of the type of mesh available

type

Substructure containing the information of element of type type

The type substructure lists the information for each element. The possible mesh types
are vtx, edg, quad, tri, quad, tet, hex, prism, and pyr. The substructure type
contains the fields listed in the table:
FIELDS

DESCRIPTION

localcoords

Local nodes coordinates

localdofcoords

Local dofs coordinates

localdofnames

Names of the local dofs

nodes

Nodes index for each element

dofs

Dofs index for each element

SPECIFY THE INFORMATION TO RETRIEVE

To specify the solver node to retrieve the xmesh information, set the property solname
as in this command:
info = mphxmeshinfo(model, 'soltag', <soltag>);

168 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

where <soltag> is the tag of the solver used to extract the xmesh information.
To retrieve the xmesh information for a specific study step node, specify it with the
property studysteptag:
info = mphxmeshinfo(model, 'studysteptag', <studysteptag>);

where <studysteptag> is the tag of either a compiled equation node or a variable

node.
In case several mesh cases have been used by a specific solver, for example, with an
automatic remeshing procedure, you can specify which mesh case to use to get the
discretization information:
info = mphxmeshinfo(model, 'meshcase', <meshcase>);

where <meshcase> is the mesh case number or the tag of the mesh case.

RETRIEVING XMESH INFORMATION

169

Navigating the Model

The model object contains all the finite element model settings. To retrieve the model
information you can navigate in the model object using a graphical user interface or
directly at the MATLAB prompt. Learn how to get the list of predefined expressions
available for a given model and how to extract the value of these expressions and also
the properties of the method used in the model.
In this section:
Navigating the Model Object Using a GUI
Navigating The Model Object At The Command Line
Finding Model Expressions
Getting Feature Model Properties
Getting Model Expressions
Getting Selection Information

Navigating the Model Object Using a GUI

The usual approach to navigate through the model object in a graphical user interface
(GUI) is to load the model object at the COMSOL Desktop. Then transfer the model
object from the COMSOL server to the COMSOL Desktop as in Sharing the model
between the COMSOL Desktop and the MATLAB prompt.
An alternative approach is to call the function mphnavigatorthat displays the model
object information in a MATLAB GUI. To run the function type at the MATLAB
prompt, enter the command:
mphnavigator

Prior to calling mphnavigator, make sure that the MATLAB object

linked the COMSOL Multiphysics model object has the same name. No
other name is currently supported.

170 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

This command pops-up a MATLAB GUI as in this figure:

If a new model object is created with the MATLAB object name model,
restart mphnavigator in order to have the updated model information.

THE MENU BAR ITEMS

The mphnavigator GUI menu bar has the following options:

The File menu, where the current model object can be saved in the MPH-format, a
new model object can be opened, and the mphnavigator window can be closed.
The Tools menu lists the navigation tools available for the model object. Search is a
shortcut to the command mphsearch that starts a GUI to search expressions or tags
in the model object (see Finding Model Expressions). Solutions starts a GUI to
display the solution object available in the COMSOL Multiphysics model object.
Show Errors lists the error or warning nodes available in the model object (see
Handling Errors and Warnings).

NAVIGATING THE MODEL

171

 The Settings menu only contains the Advanced options. Select or deselect the
advanced model object methods that are displayed in the Model Viewer tree.
The Help menu.
THE SHORTCUT ICON

Just under the menu bar are two shortcut buttonsPlot and Help.

These buttons are unavailable if no method has been selected in the Model Tree section.
The Plot button displays the geometry, the mesh, or a plot group in a MATLAB figure.
The Help button displays the page of the COMSOL API Reference Manual of the
corresponding method in your default web browser.
T H E M O D E L TRE E S E C T I O N

The Model Tree section has the list of the nodes of the model object. Use the scroll bar
to the right to scroll down the list and click the + icon to expand the model object
feature nodes.

172 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

When a feature node is selected, its associated command is listed just beneath the
model tree. Click Copy to copy syntax to the clipboard and then paste it in your script.
The Model Tree list is slightly different to the Model Builder list available in
the COMSOL Desktop. This is because mphnavigator displays all
feature nodes and does not use the same filter as in the COMSOL
Desktop to order the available feature nodes.
THE PROPERTIES SECTION

The Properties section lists the properties of a selected feature node and the associated
values.
Click Copy Table to copy the entire properties table to the clipboard, then paste into a
text or spreadsheet editor.
Click Copy to copy a selected cell in the properties table.

NAVIGATING THE MODEL

173

THE METHODS SECTION

The Methods section lists all the methods associated to the feature node selected in the
Model Tree section.
Click Filter to filter the reduce the methods list to the one that returns simple
information.
Select a method in the list to get its associated syntax at the button of the Methods
section. Use the Copy button to copy the syntax to the clipboard.

Navigating The Model Object At The Command Line

Use the command mphmodel at the MATLAB prompt to retrieve model object
information, such as tags for nodes and subnodes of a COMSOL Multiphysics model
object.
To get the list of the main feature nodes and the tags of the model object model, enter
the command:
mphmodel(model)

To list the subfeature of the node type model.feature enter the command:
mphmodel(model.feature)

To list the subfeature node of the feature node model.feature(<ftag>), enter:

mphmodel(model.feature(<ftag>))

Use the flag -struct to return the model object information to MATLAB structure:
str = mphmodel(model.feature,'-struct')

str is a MATLAB structure and the fields consist of each feature node associated to the
node model.feature.

174 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

Finding Model Expressions

Each model object contains predefined expressions that depend on the physics
interface used in the model.
The function mphsearch starts a MATLAB GUI that displays the list of all the
expressions, constants, solution variables, or parameters available in the model object.

The table has the following for each entry, the:

Name of the expression,
Expression as it is set in the property value,
Description if there is one set for the expression,
Type of the expression, and the
Path in the model object.
The Search section has a search tool to filter the list. Enter any string in the edit field
and select where to search the stringin the name, the expression, or the description
of the table entry. You can also select the type you want to list. The expression type can
be Equation, Field, Tag, VarNames, or Weak.
Click Go to display the result of the search. Click Clear to clear the search settings.
Click Copy to copy any entry of the table to the clipboard.
Click Close to close the mphsearch window.

NAVIGATING THE MODEL

175

Getting Feature Model Properties

Use the command mphgetproperties to extract at the MATLAB prompt the
properties of a specified node of the model object. Use the command:
str = mphgetproperties(model.feature)

where str is a MATLAB structure that lists all the properties and the value of the
feature node model.feature.

Getting Model Expressions

Use the command mphgetexpressions to get at the MATLAB prompt the
expressions and the descriptions of a specified node of the model object. Use the
command:
expr = mphgetexpressions(model.feature)

where model.feature is the node to get the expressions from and expr is an Nx3 cell
array where N is the number of expressions for this node.

Getting Selection Information

Use the function mphgetselection to retrieve the model selection information:
str = mphgetselection(model.selection(<seltag>))

where seltag is the tag a selection node defined in the model object. The output str
is a MATLAB structure with the following fields:
dimension, the space dimension of the geometry entity selected,
geom, the tag of the geometry node used in the selection,
entities, the list of the entity indexes listed in the selection, and
isGlobal, Boolean value to indicate if the selection is global or not.

176 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

Handling Errors and Warnings

In this section:
Errors and Warnings
Using MATLAB Tools to Handle COMSOL Exceptions
Displaying Warnings and Errors in the Model

Errors and Warnings

COMSOL Multiphysics reports these types of problems:
Errors, which prevents the program from completing a task, and
Warnings, which are problems that do not prevent the completion of a task but that
might affect the accuracy or other aspects of the model.
For both errors and warnings a message is stored in a separate node located just below
the problematic model feature node.
In case of errors, a Java Exception is thrown to MATLAB, which also breaks the
execution of the script.

Using MATLAB Tools to Handle COMSOL Exceptions

When running a model that returns an error in MATLAB, the execution of the script
is automatically stopped. You can use MATLAB tools to handle exceptions and prevent
the script from breaking. Use the try and catch MATLAB statements to offer
alternatives to a failed model.
In a loop, for example, use the try and catch statements to continue to the next
iteration. For automatic geometry or mesh generation you can use it to set the model
properties with alternative values that circumvent the problem.

Displaying Warnings and Errors in the Model

Use the command mphshowerrors to search in a given model object for warning or
error nodes. To display the error and warning messages and their location in the model
object enter the command:
mphshowerrors(model)

H A N D L I N G E RRO R S A N D WAR N I N G S

177

Alternatively mphshowerrors can also return the error and warning information in a
MATLAB variable:
str = mphshowerrors(model)

where str is an Nx2 cell array, with N the number of error and warning nodes that
contain the model object. str{i,1}, which contains the location in the model of the
i:th error/warning message, and str{i,2} contains the message of the ith
error/warning message.

178 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

Improving Performance for Large

Models
Memory management is key to successful modeling. In COMSOL Multiphysics the
finite element model can store a large amount of data depending on the complexity of
the model. Exchanging such a large amount of data between MATLAB and the
COMSOL server can be problematic in terms of memory management or execution
time. This section discusses the model settings if you are experiencing memory
problems or slowness of command execution.
Setting Java Heap Size
Disabling Model Feature Update
Disabling The Model History

Setting Java Heap Size

COMSOL Multiphysics stores the data in Java. If you are experiencing memory
problems during meshing, postprocessing operations, or when exchanging data
between the COMSOL server and MATLAB, this can mean that the Java heap size
is set with too low a value.

Increasing the memory allocated for the Java process necessarily decreases
the memory available for the solver.
Either set The COMSOL Server Java Heap Size or The MATLAB Java Heap Size.
THE COMSOL SER VER JAVA HEAP SIZE

The Java heap size settings for the COMSOL server process are stored in the
comsolserver.ini file. You can find this file in the COMSOL44/bin/<arch> directory.
<arch> correspond to the architecture of the machine where the COMSOL server is
running (win32, win64, maci64, glnx86, or glnxa64).
Edit the file with a text editor, the Java heap settings are defined as in the following
lines:
-Xss4m

IMPROVING PERFORMANCE FOR LARGE MODELS

179

-Xms40m
-Xmx1024m
-XX:MaxPermSize=256m

The values are given in Mb, modify these value to satisfy the model requirements.
TH E MATLA B JAVA HE AP S IZE

To modify the Java heap size you need to edit the java.opts file available under the
COMSOL with MATLAB start-up directory. The java.opts file is stored by default
with the following settings:
-Xss4m
-Xmx768m
-XX:MaxPermSize=256m

The values are given in Mb, modify these value to satisfy the model requirements.
To modify the MATLAB Java Heap size the java.opts file has to be stored at the
MATLAB start-up directory. This is the case when starting COMSOL with MATLAB.

If you are manually connecting MATLAB with a COMSOL server, make

sure you have the java.opts at the MATLAB start-up directory.

Disabling Model Feature Update

COMSOL Multiphysics automatically updates each feature every time the model is
edited. This ensures you that the features are built with updated expressions. For
models that contain a large amount of physics feature nodes this update operation can
take some time. It can help to deactivate the model feature update.
To disable the feature model update enter the command:
model.disableUpdates(true);

You have to enable the feature update prior to computing the solution unless the
model expressions would not be evaluated according to the model settings. Enabling
the feature update is also necessary before building the geometry or the mesh in case
these are defined using expressions.
To enable the feature model update, enter the command:
model.disableUpdates(false);

180 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

Disabling The Model History

If you run a model in a loop you can experience a slowdown when the number of
iterations increases. This happens only with a large amount of iterations. The
increasing memory requirements for storing the model history explains this slowdown.
You can see all the operations performed on the model when saving it as an M-file. If
you run a model in a loop you do not need to store the model history because it
contains the same operations as many times as you have iterations in the loop. The
solution is to disable the history recording. To do this, enter the command:
model.hist.disable

When the model history is disabled you no longer see the commands used to set up
the model when saving it as an M-file.

The function mphload automatically disables the model history when

loading a model.
To activate the model history, enter the command:
model.hist.enable

IMPROVING PERFORMANCE FOR LARGE MODELS

181

Creating a Custom GUI

You can use the MATLAB guide functionality to create a GUI and connect the
interface to a COMSOL Multiphysics model object. Each operation in the GUI sets
the value of a MATLAB variable or calls a MATLAB command. You can call
commands at the MATLAB prompt to set up a COMSOL model object or set
MATLAB variables in the COMSOL model object.
The figure below illustrates a GUI made in MATLAB and linked to a COMSOL model
object.

The simplified GUI only allows the user to compute a heat transfer problem on a given
geometry. The user can only change the radius and the position of the bottom circle
geometry. The heat source applied to the bottom circle is also defined by the user.
The button executes the building operation of the geometry and mesh. Another
button executes the computation of the solution.

182 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

COMSOL 3.5a Compatibility

COMSOL makes an effort to be backward compatible: you can load model MPH-files
created in COMSOL Multiphysics 3.5a and later versions in COMSOL Multiphysics
4.4.
When going from version 3.5a to version 4, a major revision was made to the
MATLAB interface. This revision was made to reflect changes made to the new user
interface and to support parameterized geometry operations. As a result, a new
MATLAB interface syntax is used in today's version of COMSOL Multiphysics and its
add-on product LiveLink for MATLAB.
In order to assist in the conversion process, a special compatibility mode was created
to facilitate the new syntax. This compatibility mode, together with LiveLink for
MATLAB function mphv4, is no longer supported as of COMSOL Multiphysics 4.3.
If you wish to convert a model defined with an M-file created with version 3.5a to the
version 4.4 format, we recommend the following procedure:
1 Run the M-file using COMSOL Multiphysics 3.5a and save the model, using flsave,

as an MPH-file.
2 Load the model into COMSOL Multiphysics 4.4 and verify that the model settings

have been translated correctly. In addition, verify that the model can be meshed and
solved.
3 Compact the model history and save the model as a M-file.

Compacting the Model History and Creating a Copy Using Save As in

the COMSOL Multiphysics Reference Manual
The saved M-file can now be tested if you start the current version of COMSOL
Multiphysics with MATLAB.
If you have any problems with this conversion process, please contact COMSOL's
technical support team at [email protected], or your local COMSOL
representative.

COMSOL 3.5A COMPATIBILITY

183

184 |

C H A P T E R 4 : WO R K I N G W I T H M O D E L S

Calling MATLAB Functions

This section introduces you to the MATLAB function callback from the
COMSOL Desktop and COMSOL Multiphysics model object.
In this chapter:
The MATLAB Function Feature Node

185

The MATLAB Function Feature Node

MATLAB functions are global in scope and you can use them in a model to define
model settings such as parameters, material properties, and boundary conditions.
When running the model, COMSOL Multiphysics automatically starts a MATLAB
process that evaluates the function and returns the value to the COMSOL model..
You do not need to start COMSOL with MATLAB to call a MATLAB
function from within the model; starting the COMSOL Desktop is
sufficient. The MATLAB process starts automatically to evaluate the
function.

On Linux operating systems, specify the MATLAB root directory path

MLROOT and load the gcc library when starting the COMSOL Desktop:
comsol -mlroot MLROOT -forcegcc.

Defining a MATLAB Function in the COMSOL Model

Defining a MATLAB Function in the COMSOL Model

These topics are described for the MATLAB function:
Adding the MATLAB Function Node
Defining the MATLAB Function
Plotting the Function
Example: Define the Hankel Function
A D D I N G T H E M AT L A B F U N C T I O N N O D E

To evaluate a MATLAB function from in the COMSOL Multiphysics model you need
to add a MATLAB node in the model object where the function name, the list of the
arguments, and, if required, the function derivatives, are defined.
To add a MATLAB function node, on the Home toolbar, click Functions and choose
Global>MATLAB(
).

186 |

C H A P T E R 5 : C A L L I N G M AT L A B F U N C T I O N S

The settings window of the MATLAB node has these sections:

Functions where you declare the name of the MATLAB functions and their
arguments.
Derivatives where you define the derivative of the MATLAB functions with respect
to all function arguments.
Plot Parameters where you can define the limit of the arguments value in order to
display the function in the COMSOL Desktop Graphics window.

T H E M AT L A B F U N C T I O N F E A T U R E N O D E

187

D E F I N I N G T H E M AT L A B F U N C T I O N

This figure illustrates the MATLAB settings window:

Under Functions, define the function name and the list of the function arguments.
In the table columns and rows, enter the Function name and the associated function
Arguments. The table supports multiple function definitions. You can define several

functions in the same table or add several MATLAB nodes, as you prefer.
PLOTTING THE FUNCTION

Click the Plot button (

) to display a plot of the function.

Click the Create Plot button (

) to create a plot group under the Results node.

To plot the function you first need to define limits for the arguments. Expand the Plot
Parameters section and enter the desired value in the Lower limit and Upper limit
columns. In the Plot Parameters table the number of rows correspond to the number
of input arguments of the function. The first input argument corresponds to the top
row.
In case there are several functions declared in the Functions table, only the function that
has the same number of input arguments as the number of filled in rows in the Plot
Parameters table is plotted.

188 |

C H A P T E R 5 : C A L L I N G M AT L A B F U N C T I O N S

If several functions have the same number of input arguments, the first function in the
table (from top to bottom) is plotted. Use the Move up (
) and Move down (
)
buttons to change the order of functions in the table.
EXAMPLE: DEFINE THE HANKEL FUNCTION

Assume that you want to use MATLABs Bessel function of the third kind (Hankel
function) in a COMSOL model. Add a MATLAB function node, then define the
following settings:
FUNCTION NAME

ARGUMENTS

besselh

nu, x

To plot the function you need first to define the lower and upper limits for both nu
and x. In the Plot Parameters table set the first row (which corresponds to the first
argument nu) of the Lower limit column to 0 and the Upper limit column to 5 and set
the second row (corresponding of x) of the Lower limit column to 0 and the Upper limit
column to 10:

T H E M AT L A B F U N C T I O N F E A T U R E N O D E

189

Click the Plot button (

) to get this plot:

Setting the Function Directory Path in MATLAB

To be able to run a model that use an external MATLAB function, the path directory
of the function has to be set in MATLAB before it is called by COMSOL Multiphysics
to evaluate the function.
To proceed you have these options to set the directory path in MATLAB:
Save the model MPH-file in the same directory as for the M-functions;

190 |

C H A P T E R 5 : C A L L I N G M AT L A B F U N C T I O N S

 Set the system environment variable COMSOL_MATLAB_PATH with the

M-functions directory path; or
Use the Set Path window to specify the MATLAB search path. To open the window
type pathttol at the MATLAB prompt or in the MATLAB desktop go the Home
ribbon toolbar, Environment group.

Adding a MATLAB Function with the COMSOL API Syntax

To add a MATLAB feature node to the COMSOL Multiphysics model using the
COMSOL API, enter the command:
model.func.create(<ftag>, 'MATLAB');

Define the function name and function arguments with the command:
model.func(<ftag>).setIndex('funcs', <function_name>, 0, 0);
model.func(<ftag>).setIndex('funcs', <arglist>, 0, 1);

where <function_name> is a string set with the function name and <arglist> is a
string that defines the list of the input arguments.

Function Input/Output Considerations

The functions called from COMSOL Multiphysics must support vector arguments of
any length. COMSOL calls a MATLAB function using vector arguments to reduce
the number of expensive calls from COMSOL to MATLAB. All common MATLAB
functions such as sin, abs, and other mathematical functions support vector
arguments.
When you write your own functions, remember that the input arguments
are vectors. The output must have the same size as the input. All
arguments and results must be double-precision vectors real or complex
valued.
Consider the following example function where the coefficient c depends on the x
coordinate:
function c = func1(x)
if x > 0.6
c = x/1.6;
else
c = x^2+0.3;
end

T H E M AT L A B F U N C T I O N F E A T U R E N O D E

191

This function looks good at first but it does not work in COMSOL Multiphysics
because the input x is a matrix:
Element-by-element multiplication, division, and power must be usedthat is, the
operators .*, ./, and .^. Replace expressions such as x/1.6 and x^2+0.3 with
x./1.6 and x.^2+0.3, respectively.
The comparison x 0.6 returns a matrix with ones (true) for the entries where the
expression holds true and zeros (false) where it is false. The function evaluates the
conditional statement if, and only if, all the entries are true (1).
You can replace the if statement with a single assignment to the indices retrieved from
the x 0.6 operation and another assignment to the indices where x 0,6 . The
function could then look like this:
function c = func2(x)
c = (x./1.6).*(x>0.6) + (x.^2+0.3).*(x<=0.6);

Updating Functions
If the function M-file is modified using a text editor, click Clear Functions to ensure that
the functions modifications are updated in the COMSOL Multiphysics model.

An alternative is to select the Clear functions automatically before solving check box.

Defining Function Derivatives

Automatic differentiation is not supported with MATLAB functions. In case the
MATLAB function has Jacobian contributions, its derivatives with respect to the
function input arguments need to be defined. By default COMSOL Multiphysics
assumes the derivatives to be null.
Expand the Derivatives section to define the derivatives of the function with respect to
the function arguments. In the table define the derivative for each function argument.
In the Function column enter the function name, in the Argument column enter the

192 |

C H A P T E R 5 : C A L L I N G M AT L A B F U N C T I O N S

argument. Finally in the Function derivative column enter the expression for the
corresponding derivative.

The function derivatives can also be defined by additional MATLAB

functions.
The section, Example: Define the Hankel Function, defined the function derivative by
entering the following settings in the table:
FUNCTION

ARGUMENT

FUNCTION DERIVATIVE

besselh

nu

(besselh(nu-1,x)-besselh(nu+1,x))/2

besselh

(besselh(0,x)-besselh(2,x))/2

T H E M AT L A B F U N C T I O N F E A T U R E N O D E

193

194 |

C H A P T E R 5 : C A L L I N G M AT L A B F U N C T I O N S

Command Reference
The main reference for the syntax of the commands available with LiveLink for
MATLAB is the COMSOL API Reference Manual. This section documents

additional interface functions that come with the product.

In this chapter:
Summary of Commands
Commands Grouped by Function

195

Summary of Commands
colortable

mphmesh

mphcd

mphmeshstats

mphdoc

mphmin

mpheval

mphmodel

mphevalglobalmatrix

mphmodellibrary

mphevalpoint

mphnavigator

mphgeom

mphparticle

mphgetadj

mphplot

mphgetcoords

mphsave

mphgetexpressions

mphsearch

mphgetproperties

mphselectbox

mphgetselection

mphselectcoords

mphgetu

mphshowerrors

mphglobal

mphsolinfo

mphimage2geom

mphsolutioninfo

mphinputmatrix

mphstart

mphint2

mphstate

mphinterp

mphtable

mphload

mphversion

mphmatrix

mphviewselection

mphmax

mphxmeshinfo

mphmean

196 |

CHAPTER 6: COMMAND REFERENCE

C o m m a nds G r ou p ed b y Fu n c t i on
INTERFACE FUNCTIONS
FUNCTION

PURPOSE

mphcd

Change the directory to the directory of the model.

mphdoc

Return HTML help of a specified function.

mphload

Load a COMSOL model MPH-file.

mphsave

Save a COMSOL model.

mphstart

Connect MATLAB to a COMSOL server.

mphversion

Return the version number of COMSOL Multiphysics

GEOMETRY FUNCTIONS
FUNCTION

PURPOSE

mphgeom

Plot a geometry in a MATLAB figure.

mphimage2geom

Convert image data to geometry.

mphviewselection

Display a geometric entity selection in a MATLAB figure.

MESH FUNCTIONS
FUNCTION

PURPOSE

mphmesh

Plot a mesh in a MATLAB figure.

mphmeshstats

Return mesh statistics and mesh data information.

UTILITY FUNCTIONS
FUNCTION

PURPOSE

mphgetadj

Return geometric entity indices adjacent to each other.

mphgetcoords

Return point coordinates of geometry entities.

mphgetu

Return solution vectors.

mphinputmatrix

Add matrix system for a linear solver.

mphmatrix

Get model matrices.

mphselectbox

Select a geometric entity using a rubberband/box.

mphselectcoords

Select a geometric entity using point coordinates.

mphsolinfo

Get information about a solution object.

COMMANDS GROUPED BY FUNCTION

197

FUNCTION

PURPOSE

mphsolutioninfo

Get information about solution objects and datasets

containing given parameters.

mphstate

Get state-space matrices for dynamic systems.

mphxmeshinfo

Extract information about the extended mesh.

POSTPROCESSING FUNCTIONS
FUNCTION

PURPOSE

mpheval

Evaluate expressions on node points.

mphevalglobalmatrix

Evaluate global matrix variables.

mphevalpoint

Evaluate expressions at geometry vertices.

mphglobal

Evaluate global quantities.

mphint2

Perform integration of expressions.

mphinterp

Evaluate expressions in arbitrary points or data sets.

mphmax

Perform maximum of expressions.

mphmean

Perform mean of expressions.

mphmin

Perform minimum of expressions.

mphparticle

Evaluate expressions on particle trajectories.

mphplot

Render a plot group in a figure window.

mphtable

Get table data.

MODEL INFORMATION AND NAVIGATION

198 |

FUNCTION

PURPOSE

mphgetproperties

Get properties from a model node.

mphgetexpressions

Get the model variables and parameters.

mphgetselection

Get information about a selection node.

mphmodel

Return tags for the nodes and subnodes in the COMSOL

model object.

mphmodellibrary

GUI for viewing the product model libraries.

mphnavigator

GUI for viewing the COMSOL model object.

mphsearch

GUI for searching expressions in the COMSOL model

object.

mphshowerrors

Show messages in error and warning nodes in the COMSOL

model object.

CHAPTER 6: COMMAND REFERENCE

colortable
Return a MATLAB colormap for a COMSOL Multiphysics color table.

Purpose

colortable

Syntax

map = colortable(name)

Description

map = colortable(name) returns the color table (of 1024 colors) for name, where
name can be one of the following strings:
Cyclic - A color table that varies the hue component of the hue-saturation-value

color model, keeping the saturation and value constant (equal to 1). The colors
begin with red, pass through yellow, green, cyan, blue, magenta, and return to red.
This table is useful to display periodic functions and has a sharp color gradient.
Disco - This color table spans from red through magenta and cyan to blue.
Discolight - Similar to Disco but uses lighter colors.
Grayscale - A color table that uses no color, only the gray scale varying linearly

from black to white.

Grayprint - Varies linearly from dark gray (0.95, 0.95, 0.95) to light gray (0.05,

0.05, 0.05). This color table overcomes two disadvantages that the GrayScale
color table has when used for printouts on paperit gives the impression of being
dominated by dark colors and that white cannot be distinguished from the
background.
Rainbow - The color ordering in this table corresponds to the wavelengths of the
visible part of the electromagnetic spectrum: beginning at the small-wavelength end
with dark blue, the colors range through shades of blue, cyan, green, yellow, and
red.
Rainbowlight - Similar to Rainbow, this color table uses lighter colors.
Thermal - Ranges from black through red and yellow to white, which corresponds

to the colors iron takes as it heats up.

Thermalequidistant - Similar to Thermal but uses equal distances from black to

red, yellow, and white, which means that the black and red regions become larger.
Traffic - Spans from green through yellow to red.
Trafficlight - Similar to Traffic but uses lighter colors.
Wave - Ranges linearly from blue to light gray, and then linearly from white to red.
When the range of the visualized quantity is symmetric around zero, the color red
or blue indicates whether the value is positive or negative, and the saturation
indicates the magnitude.

199

colortable
Wavelight - Similar to Wave and ranges linearly from a lighter blue to white
(instead of light gray) and then linearly from white to a lighter red.

Calling colortable is equivalent to calling the corresponding colormap function

directly.
Example

Create a rainbow color map

map = colortable('Rainbow');
map = rainbow;

200 |

CHAPTER 6: COMMAND REFERENCE

mphcd
Change directory to the directory of the model

Purpose

mphcd

Syntax

mphcd(model)

Description

mphcd(model) changes the current directory in MATLAB

to the directory where

the model was last saved.

See aalso

mphload, mphsave

201

mphdoc
Return HTML help of a specified function.

Purpose

mphdoc

Syntax

mphdoc arg1
mphdoc arg1 arg2

Description

mphdoc arg1 returns the HTML documentation associated to the function arg1.
mphdoc arg1 arg2 returns the HTML documentation associated to the feature
arg2 of the method arg1.
mphdoc arg1 -web returns the HTML documentation in the default web browser.

Example

Create a model object

model = ModelUtil.creat('Model')

Get the documentation for the mesh node

mphdoc model.mesh

Get the documentation of the rectangle geometry feature

mphdoc model.geom Rectangle

Display the documentation in the default web browser

mphdoc model.sol -web

202 |

CHAPTER 6: COMMAND REFERENCE

mpheval
Evaluate expressions on node points.

Purpose

mpheval

Syntax

pd = mpheval(model,{e1,...,en},...)

Description

pd = mpheval(model,{e1,...,en},...) returns the post data pd for the

expressions e1,...,en.
The output value pd is a structure with fields expr, p, t, ve, unit and fields for data
values.
The field expr contains the expression name evaluated.
For each expression e1,...,en a field with the name d1,... dn is added with
the numerical values. The columns in the data value fields correspond to node
point coordinates in columns in p. The data contains only the real part of
complex-valued expressions.
The field p contains node point coordinate information. The number of rows in
p is the number of space dimensions.
The field t contains the indices to columns in p of a simplex mesh, each column
in t representing a simplex.
The field ve contains indices to mesh elements for each node point.
The field unit contains the list of the unit for each expression.
The function mpheval accepts the following property/value pairs:
TABLE 6-1: PROPERTY/VALUE PAIRS FOR THE MPHEVAL COMMAND.
PROPERTY

PROPERTY
VALUE

DEFAULT

DESCRIPTION

Complexfun

off | on

on

Use complex-valued functions with

real input

Complexout

off | on

off

Return complex values

Dataonly

off | on

off

Only return expressions value

Dataset

String

Edim

point |
edge |
boundary |
domain | 0
| 1 | 2 | 3

Geometry
space
dimension

Evaluate on elements with this

space dimension

Matherr

off | on

off

Error for undefined operations or

expressions

Outersolnum

Positive
integer |
all | end

Solution number for parametric

sweep

Data set tag

203

mpheval

TABLE 6-1: PROPERTY/VALUE PAIRS FOR THE MPHEVAL COMMAND.

PROPERTY

PROPERTY
VALUE

DEFAULT

DESCRIPTION

Pattern

lagrange |
gauss

lagrange

Specifies if evaluation takes place in

Lagrange points or in Gauss points

Phase

Scalar

Phase angle in degrees

Recover

off | ppr |
pprint

off

Accurate derivative recovery

Refine

Integer

Refinement of elements for

evaluation points

Selection

Integer
vector |
string |
all

All
domains

Set selection tag or entity number

Smooth

Internal |
none |
everywhere

internal

Smoothing setting

Solnum

Integer
vector |
all | end

all

Solutions for evaluation

Double
array

Times for evaluation

The property Dataset controls which data set is used for the evaluation. Data Sets
contain or refer to the source of data for postprocessing purposes. Evaluation is
supported only on Solution Data Sets.
The property Edim decides which elements to evaluate on. Evaluation takes place
only on elements with space dimension Edim. If not specified, Edim equal to the
space dimension of the geometry is used. The setting is specified as one of the
following strings 'point', 'edge', 'boundary' or 'domain'. In previous
versions it was only possible to specify Edim as a number. For example, in a 3D
model, if evaluation is done on edges (1D elements), Edim is 1. Similarly, for
boundary evaluation (2D elements), Edim is 2, and for domain evaluation (3D
elements), Edim is 3 (default in 3D).
Use Recover to recover fields using polynomial-preserving recovery. This
techniques recover fields with derivatives such as stresses or fluxes with a higher
theoretical convergence than smoothing. Recovery is expensive so it is turned off by
default. The value pprint means that recovery is performed inside domains. The
value ppr means that recovery is also applied on all domain boundaries.

204 |

CHAPTER 6: COMMAND REFERENCE

mpheval
The property Refine constructs evaluation points by making a regular refinements
of each element. Each mesh edge is divided into Refine equal parts.
The property Smooth controls if the post data is forced to be continuous on element
edges. When Smooth is set to internal, only elements not on interior boundaries are
made continuous.
The property Solnum is used to select the solution to plot when a parametric,
eigenvalue or time-dependent solver has been used to solve the problem.
The property Outersolnum is used to select the solution to plot when a parametric
sweep has been used in the study.
When the property Phase is used, the solution vector is multiplied with
exp(i*phase) before evaluating the expression.

The expressions e1,...,en are evaluated for one or several solutions. Each solution
generates an additional row in the data fields of the post data output structure. The
property Solnum and t control which solutions are used for the evaluations. The
Solnum property is available when the data set has multiple solutions, for example
in the case of parametric, eigenfrequency, or time-dependent solutions. The t
property is available only for time-dependent problems. If Solnum is provided, the
solutions indicated by the indices provided with the Solnum property are used. If t
is provided solutions are interpolated. If neither Solnum nor t is provided, all
solutions are evaluated.
For time-dependent problems, the variable t can be used in the expressions ei. The
value of t is the interpolation time when the property t is provided, and the time
for the solution, when Solnum is used. Similarly, lambda and the parameter are
available as eigenvalues for eigenvalue problems and as parameter values for
parametric problems, respectively.
Example

Evaluate the temperature at node points:

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
std.feature.create('stat','Stationary');
std.run;
dat = mpheval(model,'T');

Evaluate both the total heat flux magnitude and the temperature:
data = mpheval(model,{'ht.tfluxMag', 'T'});

Evaluate the temperature and return the data only:

205

mpheval
data = mpheval(model,'T','dataonly','on');

Evaluate the temperature at the node points in domain 2:

data = mpheval(model,'T','selection',2);

Evaluate the temperature at the node points on boundary 7:

data = mpheval(model,'T','selection',7,'edim','boundary');

Evaluate the temperature at second order Lagrange points:

data = mpheval(model,'T','refine',2);

Evaluate the temperature at the Gauss points:

data = mpheval(model,'T','pattern','gauss');

Evaluate the temperature at every time step computed with power set to 30:
model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
param = std.feature.create('param','Parametric');
time = std.feature.create('time','Transient');
time.set('tlist', 'range(0,1,25)');
param.setIndex('pname','power',0);
param.setIndex('plistarr','30 60 90',0);
std.run;
data = mpheval(model,'T','dataset','dset2');

Evaluate the temperature at the fifth time step:

data = mpheval(model,'T','dataset','dset2','solnum',5);

Evaluate the temperature at 10.5 sec and 15.2 sec:

data = mpheval(model,'T','dataset','dset2','t',[10.5,15.2]);

Evaluate the temperature at every time step computed with power set to 90:
data = mpheval(model,'T','dataset','dset2','outersolnum',3);
See also

206 |

CHAPTER 6: COMMAND REFERENCE

mphevalpoint, mphglobal, mphinputmatrix, mphinterp

mphevalglobalmatrix
Evaluate global matrix variables.

Purpose

mphevalglobalmatrix

Syntax

M = mphevalglobalmatrix(model,expr,...)

Description

M = mphevalglobalmatrix(model,expr,...) evaluates the global matrix of the

variable expr and returns the full matrix M.

The function mphevalglobalmatrix accepts the following property/value pairs:
TABLE 6-2: PROPERTY/VALUE PAIRS FOR THE MPHEVAL COMMAND.
PROPERTY

PROPERTY
VALUE

Dataset

String

DEFAULT

DESCRIPTION

Data set tag

Note: S-parameters evaluation requires the RF module.

Example

Load lossy_circulator_3d.mph from the RF Modules model library:

model = mphload('lossy_circulator_3d.mph');

Evaluate the S-parameters matrix using the solution data set dset4:
M = mphevalglobalmatrix(model,'emw.SdB','dataset','dset4');
See also

mpheval, mphinterp, mphglobal

207

mphevalpoint
Evaluate expressions at geometry vertices.

Purpose

mphevalpoint

Syntax

[v1,...,vn] = mphevalpoint(model,{e1,...,en},...)
[v1,...,vn,unit] = mphevalpoint(model,{e1,...,en},...)

Description

[v1,...,vn] = mphevalpoint(model,{e1,...,en},...) returns the results

from evaluating the expressions e1,...,en at the geometry vertices. The values
v1,...,vn can either be a cell array or a matrix depending on the options.
[v1,...,vn,unit] = mphevalpoint(model,{e1,...,en},...) also returns

the unit of all expressions e1,...,en in the 1xN cell array unit.
The function mphevalpoint accepts the following property/value pairs:
TABLE 6-3: PROPERTY/VALUE PAIRS FOR THE MPHEVAL COMMAND.

208 |

PROPERTY

PROPERTY
VALUE

Dataset

String

Dataseries

none | mean
| int | max
| min | rms
| std | var

none

The operation that is applied to the

data series formed by the
evaluation

Matrix

off | on

on

Return a matrix if possible

Minmaxobj

Real | abs

real

The value being treated if

Dataseries is set to max or min

Outersolnum

Positive
integer |
all | end

Solution number for parametric

sweep

Selection

Integer
vector |
string |
all

All
domains

Set selection tag or entity number

Smooth

Internal |
none |
everywhere

internal

Smoothing setting

Solnum

Integer
vector |
all | end

all

Solutions for evaluation

Squeeze

on | off

on

Squeeze singleton dimension

Double
array

CHAPTER 6: COMMAND REFERENCE

DEFAULT

DESCRIPTION

Data set tag

Times for evaluation

mphevalpoint
The property Dataset controls which data set is used for the evaluation. Data Sets
contain or refer to the source of data for postprocessing purposes. Evaluation is
supported only on Solution Data Sets.
The Dataseries property is used to control any filtering of the data series. The
supported operations are: average (mean), integral (int), maximum (max),
minimum (min), root mean square (rms), standard deviation (std) and variance
(var).
Set the property Matrix to off to get the results in a cell array format.
In case the property Datseries is either min or max, you can specify the how the
value are treated using the property Minmaxobj. Use either the real data or the
absolute data.
The property Solnum is used to select the solution to plot when a parametric,
eigenvalue or time-dependent solver has been used to solve the problem.
The expressions e1,...,en are evaluated for one or several solutions. Each solution
generates an additional row in the data fields of the post data output structure. The
property Solnum and t control which solutions are used for the evaluations. The
Solnum property is available when the data set has multiple solutions, for example
in the case of parametric, eigenfrequency, or time-dependent solutions. The t
property is available only for time-dependent problems. If Solnum is provided, the
solutions indicated by the indices provided with the Solnum property are used. If t
is provided solutions are interpolated. If neither Solnum nor t is provided, all
solutions are evaluated.
For time-dependent problems, the variable t can be used in the expressions ei. The
value of t is the interpolation time when the property t is provided, and the time
for the solution, when Solnum is used. Similarly, lambda and the parameter are
available as eigenvalues for eigenvalue problems and as parameter values for
parametric problems, respectively.
Example

Evaluate the temperature on all geometry points:

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
std.feature.create('stat','Stationary'); std.run;
T = mphevalpoint(model,'T');

Evaluate the temperature on point 5:

T = mphevalpoint(model,'T','selection',5);

209

mphevalpoint
Evaluate the temperature and the magnitude of the total heat flux on point 5:
[T, heatflux, unit] = mphevalpoint(model,{'T','ht.tfluxMag'},...
'selection',5);

Evaluate the temperature at every time step computed with power set to 30:
model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
param = std.feature.create('param','Parametric');
time = std.feature.create('time','Transient');
time.set('tlist', 'range(0,1,25)');
param.setIndex('pname','power',0)
param.setIndex('plistarr','30 60 90',0);
std.run;
T = mphevalpoint(model,'T','selection',5,'dataset','dset2');

Evaluate the temperature at the seventh time step:

T = mphevalpoint(model,'T','selection',5,'dataset','dset2',...
'solnum',7);

Evaluate the temperature at 10.5 sec:

T = mphevalpoint(model,'T','selection',5,'dataset','dset2',...
't',10.5);

Evaluate the temperature on point 5 computed with power set to 90:

T = mphevalpoint(model,'T','selection',5,'dataset','dset2',...
'outersolnum',3)

Evaluate the temperature average over all time steps:

T_avg = mphevalpoint(model,'T','selection',5,...
'dataset','dset2','dataseries','average');
See also

210 |

mpheval, mphglobal, mphinterp

CHAPTER 6: COMMAND REFERENCE

mphgeom
Plot a geometry in a MATLAB figure.

Purpose

mphgeom

Syntax

mphgeom(model)
mphgeom(model,geomtag,...)

Description

mphgeom(model) plots the model geometry in a MATLAB figure.

mphgeom(model,geomtag,...) plots the model geometry with the tag geomtag

in a MATLAB figure.
The function mphgeom accepts the following property/value pairs:
TABLE 6-4: PROPERTY/VALUE PAIRS FOR THE MPHGEOM COMMAND
PROPERTY

VALUE

DEFAULT

DESCRIPTION

Parent

Double

Parent axes

Selection

Positive
integer
array

Selection

Entity

point |
edge |
boundary |
domain

Geometric entity to
select

Build

on | off |
current |
string

on

Build the geometry

before plotting

Edgecolor

Char

Edge color

Edgelabels

on | off

off

Show edge labels

Edgelabelscolor

Char

Color for edge labels

Edgemode

on | off

on

Show edges

Facealpha

Double

Set transparency value

Facelabels

on | off

off

Show face labels

Facelabelscolor

Char

Color for face labels

Facemode

on | off

on

Show faces

Vertexlabels

on | off

off

Show vertex labels

Vertexlabelscolor

Char

Color for vertex

labels

Vertexmode

on | off

off

Show vertices

The Build property determines if mphgeom build the geometry prior to display it.
If the Build property is set with a geometric object tag, the geometry is built up to
that object. mphgeom only displays built geometry objects.

211

mphgeom

Example

Plot the model geometry:

model = mphload('model_tutorial_llmatlab.mph');
mphgeom(model)

Plot the model geometry with face labels:

mphgeom(model,'geom1','facelabels','on','facelabelscolor','r');

Plot boundaries 7, 8, 9 and 11:

mphgeom(model,'geom1','entity','boundary',...
'selection',[7:9,11]);

Plot the model geometry on an existing axis:

figure(2);
mphgeom(model, 'geom1','parent', gca);
See also

212 |

mphmesh, mphviewselection

CHAPTER 6: COMMAND REFERENCE

mphgetadj
Return geometry entity indices that are adjacent to other.

Purpose

mphgetadj

Syntax

n = mphgetadj(model,geomtag,returntype,adjtype,adjnumber)

Description

n = mphgetadj(model,geomtag,returntype,adjtype,adjnumber) returns the

indices of the adjacent geometry entities.

returntype is the type of the geometry entities whose index are returned.
adjtype is the type of the input geometry entity.

The entity type can be one of 'point', 'edge', 'boundary' or 'domain'

following the entity space dimension defined below:

'domain': maximum geometry space dimension

'boundary': maximum geometry space dimension -1

'edges': 1(only for 3D geometry)

Example

'point': 0

Return the indices of the boundaries adjacent to point 2:

model = mphload('model_tutorial_llmatlab');
bnd_idx = mphgetadj(model, 'geom1', 'boundary', 'point', 2);

Return the indices of the points adjacent to domain 2:

pt_idx = mphgetadj(model, 'geom1', 'point', 'domain', 2);
See also

mphgetcoords, mphselectbox, mphselectcoords

213

mphgetcoords
Return point coordinates of geometry entities.

Purpose

mphgetcoords

Syntax

c = mphgetcoords(model,geomtag,entitytype,entitynumber)

Description

c = mphgetcoords(model,geomtag,entitytype,entitynumber) returns the

coordinates of the points that belong to the entity object with the type entitytype
and the index entitynumber.
The entitytype property can be one of 'point', 'edge', 'boundary' or
'domain' following the entity space dimension defined below:

'domain': maximum geometry space dimension

'boundary': maximum geometry space dimension -1

'edge': 1 (only for 3D geometry)

'point': 0
Example

Return the coordinates of points that belong to domain 2:

model = mphload('model_tutorial_llmatlab');
c0 = mphgetcoords(model, 'geom1', 'domain', 2);

Return the coordinates of points that belong to boundary 5:

c1 = mphgetcoords(model, 'geom1', 'boundary', 5);

Return the coordinates of point number 10:

c2 = mphgetcoords(model, 'geom1', 'point', 10);
See also

214 |

mphgetadj, mphselectbox, mphselectcoords

CHAPTER 6: COMMAND REFERENCE

mphgetexpressions
Get the model variables and model parameters expressions.

Purpose

mphgetexpressions

Syntax

expr = mphgetexpressions(modelnode)

Description

expr = mphgetexpressions(modelnode) returns expressions from the node

modelnode as a cell array. expr contains the list of the variable names, the variable
expressions and the variable descriptions.

Note that not all nodes have expressions defined.

Example

Get the expressions defined in the parameters node of the model

model_tutorial_llmatlab.mph:
model = mphload('model_tutorial_llmatlab');
expr = mphgetexpressions(model.param)

See also

mphnavigator, mphmodel

215

mphgetproperties
Get the properties from a model node

Purpose

mphgetproperties

Syntax

mphproperties(modelnode)

Description

mphproperties(modelnode) returns properties that are defined for the node

modelnode.

Example

Build the mesh in the model model_tutorial_llmatlab.mph and get the mesh
size properties:
model = mphload('model_tutorial_llmatlab');
model.mesh('mesh1').run;
prop = mphgetproperties(model.mesh('mesh1').feature('size'))

See also

216 |

mphnavigator

CHAPTER 6: COMMAND REFERENCE

mphgetselection
Get information about a selection node.

Purpose

mphgetselection

Syntax

info = mphgetselection(selnode)

Description

info = mphgetselection(selnode) returns the selection data of the selection

node selnode.
The output info is a MATLAB structure defined with the following fields:
dimension, the space dimension of the geometry entity selected.
geom, the geometry tag.
entities, the indexes of the selected entities.
isGlobal, a Boolean expression that indicates if the selection is global.
Example

Add a selection node to the model busbar.mph and retrieve its information:
model = mphload('model_tutorial_llmatlab.mph');
ball = model.selection.create('ball','Ball');
ball.set('entitydim',2);
ball.set('posz',11e-3');
ball.set('r',1e-5);
info = mphgetselection(model.selection('ball'))

See also

mphnavigator

217

mphgetu
Return solution vector.

Purpose

mphgetu

Syntax

U = mphgetu(model,...)
[U,Udot] = mphgetu(model,...)

Description

U = mphgetu(model) returns the solution vector U for the default solution data set.
[U,Udot] = mphgetu(model,...) returns in addition Udot, which is the time

derivative of the solution vector. This syntax is available for a time-dependent

solution only.
For a time-dependent and parametric analysis type, the last solution is returned by
default. For an eigenvalue analysis type the first solution number is returned by
default.
The function mphgetu accepts the following property/value pairs:
TABLE 6-5: PROPERTY/VALUE PAIRS FOR THE MPHGETU COMMAND
PROPERTY

VALUE

DEFAULT

DESCRIPTION

Solname

String

Auto

Solver node tag

Solnum

Positive integer
vector

Auto

Solution for evaluation

Type

String

Sol

Solution type

Matrix

off | on

on

Store as matrix if possible

The Solname property set the solution data set to use associated with the defined
solver node.
Type is used to select the solution type. This is 'Sol' by default. The valid types are:
'Sol' (main solution), 'Reacf' (reaction force), 'Adj' (adjoint solution),
'Fsens' (functional sensitivity) and 'Sens' (forward sensitivity).
If Solnum is a vector and the result has been obtained with the same mesh then the
solution is stored in a matrix if the Matrix option is set to 'on'
Example

Extract the solution vector:

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
std.feature.create('stat','Stationary');
std.run;
U = mphgetu(model);

Extract the reaction force vector:

218 |

CHAPTER 6: COMMAND REFERENCE

mphgetu
reacf = mphgetu(model,'type','reacf');

Extract the solution vectors for the first and the last time step:
model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
param = std.feature.create('param','Parametric');
time = std.feature.create('time','Transient');
time.set('tlist', 'range(0,1,25)');
param.setIndex('pname','power',0);
param.setIndex('plistarr','30 60 90',0);
std.run;
U = mphgetu(model,'solnum',[1,26]);

Extract the solution vector computed with power set to 30:

U = mphgetu(model,'soltag','sol3');
See also

mphsolinfo

219

mphglobal
Evaluate global quantities.

Purpose

mphglobal

Syntax

[d1,...,dn] = mphglobal(model,{e1,...,en},...)
[d1,...,dn,unit] = mphglobal(model,{e1,...,en},...)

Description

[d1,...,dn] = mphglobal(model,{e1,...,en},...) returns the results from

evaluating the global quantities specified in the string expression e1,..., en.
[d1,...,dn,unit] = mphglobal(model,{e1,...,en},...) also returns the
unit of the expressions e1,..., en. unit is a nx1 cell array.

The function mphglobal accepts the following property/value pairs:

TABLE 6-6: PROPERTY/VALUE PAIRS FOR THE MPHGLOBAL COMMAND.
PROPERTY

PROPERTY VALUE

DEFAULT

DESCRIPTION

Complexfun

off | on

on

Use complex-valued
functions with real input

Complexout

off | on

off

Return complex values

Dataset

String

Active solution
data set

Data set tag

Matherr

off | on

off

Error for undefined

operations or expressions

Outersolnum

Positive
integer | all
| end

Solution number for

parametric sweep

Phase

Scalar

Phase angle in degrees

Solnum

Integer vector
| all | end

all

Solution for evaluation

Double array

Time for evaluation

Unit

String | cell
array

Unit to use for the

evaluation

The property Dataset controls which data set is used for the evaluation. Data Sets
contain or refer to the source of data for postprocessing purposes. Evaluation is
supported only on solution data sets.
When the property Phase is used, the solution vector is multiplied with
exp(i*phase) before evaluating the expression.
The expressions ei are evaluated for one or several solutions. Each solution
generates an additional row in the output data array di. The property Solnum and
t control which solutions are used for the evaluations. The Solnum property is
available when the data set has multiple solutions, for example in the case of

220 |

CHAPTER 6: COMMAND REFERENCE

mphglobal
parametric, eigenfrequency, or time-dependent solutions. The t property is
available only for time-dependent problems. If Solnum is provided, the solutions
indicated by the indices provided with the Solnum property are used. If t is provided
solutions are interpolated. If neither Solnum nor t is provided, all solutions are
evaluated.
For time-dependent problems, the variable t can be used in the expressions ei. The
value of t is the interpolation time when the property t is provided, and the time
for the solution, when Solnum is used. Similarly, lambda and the parameter are
available as eigenvalues for eigenvalue problems and as parameter values for
parametric problems, respectively.
In case of multiple expression if the unit property is defined with a string, the same
unit is used for both expressions. To use different units, set the property with a cell
array. In case of inconsistent unit definition, the default unit is used instead.
Solnum is used to select the solution number when a parametric, eigenvalue or
time-dependent solver has been used.
Outersolnum is used to select the outer solution number when a parametric sweep

has been used in the study step node.

Example

Evaluate the maximum temperature in the model

model = mphload('model_tutorial_llmatlab');
model.cpl.create('maxop','Maximum','geom1').selection.all;
std = model.study.create('std');
std.feature.create('stat','Stationary');
std.run;
maxT = mphglobal(model,'maxop(T)')

Evaluate the maximum temperature in the model in degrees Celsius

maxT = mphglobal(model,'maxop(T)','unit','degC')

Evaluate a global expression at every time step computed with power set to 30:
model = mphload('model_tutorial_llmatlab');
model.cpl.create('maxop', 'Maximum', 'geom1').selection.all;
std = model.study.create('std');
param = std.feature.create('param','Parametric');
time = std.feature.create('time','Transient');
time.set('tlist', 'range(0,1,25)');
param.setIndex('pname','power',0);
param.setIndex('plistarr','30 60 90',0);

221

mphglobal
std.run;
maxT = mphglobal(model,'maxop(T)','dataset','dset2');

Evaluate maxop(T) for the first and fifth time step:

maxT = mphglobal(model,'maxop(T)',dataset','dset2',...
'solnum',[1,5]);

Evaluate maxop(T) at 20.512 sec:

maxT = mphglobal(model,'maxop(T)',dataset','dset2',...
't',20.512);

Evaluate maxop(T) at every time step computed with power set to 90:
maxT = mphglobal(model,'maxop(T)',dataset','dset2',...
'outersolnum',3);
See also

222 |

mpheval, mphevalpoint, mphinterp

CHAPTER 6: COMMAND REFERENCE

mphimage2geom
Convert image data to geometry.

Purpose

mphimage2geom

Syntax

model = mphimage2geom(imagedata,level,...)

Description

model = mphimage2geom(imagedata,level,...) converts the image contained

in imagedata into a geometry which is returned in the model object model.

The contour of the image is defined by the value level. imagedata must be a 2D
matrix.
The function mphimage2geom accepts the following property/value pairs:
TABLE 6-7: PROPERTY/VALUE PAIRS FOR THE MPHIMAGE2GEOM COMMAND.
PROPERTY

PROPERTY VALUE

DEFAULT

DESCRIPTION

Rtol

Value

1e-3

Relative tolerance for

interpolation curves

Type

Solid | closed
| open

solid

Type of geometry object

Curvetype

Auto | polygon

auto

Type of curve to create the

geometry object

Scale

Value

Scale factor from pixels to

geometry scale

Mindist

Value

Minimum distance between

coordinates in curves (in
pixels)

Compose

on | off

on

Create compose nodes for

overlapping solids

Rectangle

on | off

off

Insert rectangle in the

geometry

The default curve types creates a geometry with the best suited geometrical
primitives. For interior curves this is Interpolation Curves and for curves that are
touching the perimeter of the image, Polygons is used.
Example

Create a set of point coordinates:

p = (peaks+7)*5;

Display contour plot of the point data:

figure(1); [c,h] = contourf(p); clabel(c, h); colorbar

Create a geometry object following the contour made with point of value 50 and
set a scaling factor of 1e-3:

223

mphimage2geom
model = mphimage2geom(p, 50,'scale',1e-3);
figure(2); mphgeom(model)

Save the model using MPH-format:

filename = fullfile(tempdir,'geom_sequence');
mphsave(model,filename);

Add the newly generated 2D geometry into an existing 3D model:

model = mphload('model_tutorial_llmatlab');
wp1 = model.geom('geom1').feature.create('wp1', 'WorkPlane');
wp1.set('quickz', '1e-2');
wp1.geom.insertFile(filename, 'geom1');
mphgeom(model)

224 |

CHAPTER 6: COMMAND REFERENCE

mphinputmatrix
Add matrix system for linear solver.

Purpose

mphinputmatrix

Syntax

mphinputmatrix(model,str,soltag,soltypetag)

Description

mphinputmatrix(model,str,soltag,soltypetag) adds the system matrices

and vectors stored in the MATLAB structure str to the model. The system

matrices is associated to the linear solver configuration defined with the tag soltag
and solved with the solver defined with the tag soltypetag.
soltypetag can only be one of the following solver type: Stationary, Eigenvalue,

Time.
A valid structure for a stationary solver includes the following fields:
TABLE 6-8: PROPERTY/VALUE PAIRS FOR THE MPHINT2 COMMAND.
FIELD NAME

DESCRIPTION

Stiffness matrix

Load vector

Constraint vector

Constraint Jacobian

A valid structure for a time-dependent/ eigenvalue solver includes the following

fields:
TABLE 6-9: PROPERTY/VALUE PAIRS FOR THE MPHINT2 COMMAND.
FIELD NAME

DESCRIPTION

Stiffness matrix

Load vector

Constraint vector

Constraint Jacobian

Damping matrix

Mass matrix

There is also the possibility to include the constraint force Jacobian vector NF.
Once the matrix system is loaded in the model, the solver configuration is set ready
to run.

225

mphinputmatrix

Note: The system matrices are not stored in the model when it is saved as a
MPH-file or loaded into the COMSOL Desktop.

Example

Extract the linear stationary matrix system in MATLAB:

model = mphload('model_tutorial_llmatlab');
std1 = model.study.create('std1');
std1.feature.create('stat', 'Stationary');
sol1 = model.sol.create('sol1');
sol1.study('std1');
st1 = sol1.feature.create('st1', 'StudyStep');
st1.set('studystep', 'stat');
sol1.feature.create('s1', 'Stationary');
str = mphmatrix(model,'sol1','out',{'K','L','M','N'},...
'initmethod','sol','initsol','zero');

Change the linear system by scaling the stiffness matrix and insert the system
matrices back to the model:
str.K = str.K*0.5;
mphinputmatrix(model,str,'sol1','s1')

Run the solver configuration:

model.sol('sol1').runAll;
See also

226 |

mphmatrix, mphxmeshinfo

CHAPTER 6: COMMAND REFERENCE

mphint2
Perform integration of expressions.

Purpose

mphint2

Syntax

[v1,...,v2] = mphint2(model,{e1,...,en},edim,...)
[v1,...,v2,unit] = mphint2(model,{e1,...,en},edim,...)

Description

[v1,...,vn] = mphint2(model,{e1,...,en},...) evaluates the integrals of

the string expressions e1,...,en and returns the result in N matrices v1,...,vn
with M rows and P columns. M is the number of inner solution and P the number
of outer solution used for the evaluation. edim defines the element dimension, as a
string: line, surface, volume or as an integer value.
[v1,...,vn] = mphint2(model,{e1,...,en},...) also returns the units of the

integral in a 1xN cell array.

The function mphint2 accepts the following property/value pairs:
TABLE 6-10: PROPERTY/VALUE PAIRS FOR THE MPHINT2 COMMAND.
PROPERTY

PROPERTY VALUE

DEFAULT

DESCRIPTION

Dataset

String

active
solution
data set

Data set tag

Intorder

Positive integer

Integration order

Intsurface

on | off

off

Compute surface integral

Intvolume

on | off

off

Compute volume integral

Matrix

off | on

on

Returns data as a matrix or

as a cell

Method

auto |
integration |
summation

auto

Integration method

Outersolnum

Positive integer
| all | end

Solution number for

parametric sweep

Selection

Integer vector |
string | all

all

Selection list or named

selection

Solnum

Integer vector |
end | all

all

Solution for evaluation

Squeeze

on | off

on

Squeeze singleton
dimensions

Double array

Time for evaluation

The property Dataset controls which data set is used for the evaluation. Data Sets
contain or refer to the source of data for postprocessing purposes. Evaluation is
supported only on Solution Data Sets.

227

mphint2
The expressions e1,...,en are integrated for one or several solutions. Each
solution generates an additional column in the returned matrix. The property
Solnum and t control which solutions are used for the integrations. The Solnum
property is available when the data set has multiple solutions, for example in the case
of parametric, eigenfrequency, or time-dependent solutions. The t property is
available only for time-dependent problems. If Solnum is provided, the solutions
indicated by the indices provided with the Solnum property are used. If t is provided
solutions are interpolated. If neither Solnum nor t is provided, all solutions are
evaluated.
For time-dependent problems, the variable t can be used in the expressions ei. The
value of t is the interpolation time when the property t is provided, and the time
for the solution, when Solnum is used. Similarly, lambda and the parameter are
available as eigenvalues for eigenvalue problems and as parameter values for
parametric problems, respectively.
The unit property defines the unit of the integral, if a inconsistent unit is entered,
the default unit is used. In case of multiple expression, if the unit property is
defined with a string, the same unit is used for both expressions. To use different
units, set the property with a cell array. In case of inconsistent unit definition, the
default unit is used instead.
Solnum is used to select the solution number when a parametric, eigenvalue or
time-dependent solver has been used.
Outersolnum is used to select the outer solution number when a parametric sweep

has been used in the study step node.

Example

Integrate the normal heat flux across all boundaries:

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
std.feature.create('stat','Stationary');
std.run;
[Q, unit] = mphint2(model,'ht.ntflux','surface');

Integrate the normal heat flux across all exterior boundaries

[Q, unit] = mphint2(model,'ht.ntflux','surface',...
'selection',[1:5,7:12]);
See also

228 |

mpheval, mphevalpoint, mphglobal, mphinterp

CHAPTER 6: COMMAND REFERENCE

mphinterp
Evaluate expressions in arbitrary points or data sets.

Purpose

mphinterp

Syntax

[v1,...,vn] = mphinterp(model,{e1,...,en},'coord',coord,...)
[v1,...,vn] = mphinterp(model,{e1,...,en},'dataset',dsettag,...)
[v1,...,vn,unit] = mphinterp(model,{e1,...,en},...)

Description

[v1,...,vn] = mphinterp(model,{e1,...,en},'coord',coord,...)

evaluates expressions e1,...en at the coordinates specified in the double matrix

coord. Evaluation is supported only on Solution Data Sets.
[v1,...,vn] = mphinterp(model,{e1,...,en},'dataset',dsettag,...)

evaluates expressions e1,...en on the specified data set dsettag. In this case the
data set needs to be of a type that defines an interpolation in itself, such as cut planes,
revolve, and so forth.
[v1,...,vn,unit] = mphinterp(model,{e1,...,en},...) returns in addition

the unit of the expressions.

The function mphinterp accepts the following property/value pairs:
TABLE 6-11: PROPERTY/VALUE PAIRS FOR THE MPHINTERP COMMAND.
PROPERTY

PROPERTY
VALUE

DEFAULT

DESCRIPTION

Complexfun

off | on

on

Use complex-valued functions

with real input

Complexout

off | on

off

Return complex values

Coord

Double
array

Coorderr

off | on

off

Give an error message if all

coordinates are outside the
geometry

Dataset

String

Auto

Data set tag

Edim

'point' |
'edge' |
'boundary'
| 'domain'
| 0 | 1 | 2
| 3

Geometry
space
dimension

Element dimension for

evaluation

Ext

Value

0.1

Extrapolation control

Matherr

off | on

off

Error for undefined operations

or expressions

Outersolnum

Positive
integer |
all | end

Solution number for parametric

sweep

Coordinates for evaluation

229

mphinterp

TABLE 6-11: PROPERTY/VALUE PAIRS FOR THE MPHINTERP COMMAND.

PROPERTY

PROPERTY
VALUE

DEFAULT

DESCRIPTION

Phase

Scalar

Phase angle in degrees

Recover

off | ppr |
pprint

off

Accurate derivative recovery

Selection

Positive
Integer
array | all

all

Selection list

Solnum

Positive
integer
array | all
| end

all

Inner solutions for evaluation

Double
array

Time for evaluation

Unit

String |
Cell array

Unit to use for the evaluation

The columns of the matrix coord are the coordinates for the evaluation points. If
the number of rows in coord equals the space dimension, then coord are global
coordinates, and the property Edim determines the dimension in which the
expressions are evaluated. For instance, Edim='boundary' means that the
expressions are evaluated on boundaries in a 3D model. If Edim is less than the space
dimension, then the points in coord are projected onto the closest point on a
domain of dimension Edim. If, in addition, the property Selection is given, then
the closest point on domain number Selection in dimension Edim is used.
If the number of rows in coord is less than the space dimension, then these
coordinates are parameter values on a geometry face or edge. In that case, the
domain number for that face or edge must be specified with the property
Selection.
The expressions that are evaluated can be expressions involving variables, in
particular physics interface variables.
The matrices v1,...,vn are of the size k-by-size(coord,2), where k is the number
of solutions for which the evaluation is carried out, see below. The value of
expression ei for solution number j in evaluation point coord(:,m) is vi(j,m).
The vector pe contains the indices m for the evaluation points code(:,m) that are
outside the mesh, or, if a domain is specified, are outside that domain.

230 |

CHAPTER 6: COMMAND REFERENCE

mphinterp
The property Data controls which data set is used for the evaluation. Data Sets
contain or refer to the source of data for postprocessing purposes. Evaluation is
supported only on Solution Data Sets. The active solution data set is used by default.
The property Edim decides which elements to evaluate on. Evaluation takes place
only on elements with space dimension Edim. If not specified, Edim equal to the
space dimension of the geometry is used. The setting is specified as one of the
following strings 'point', 'edge', 'boundary' or 'domain'. In previous
versions it was only possible to specify Edim as a number. For example, in a 3D
model, if evaluation is done on edges (1D elements), Edim is 1. Similarly, for
boundary evaluation (2D elements), Edim is 2, and for domain evaluation (3D
elements), Edim is 3 (default in 3D).
Use Recover to recover fields using polynomial-preserving recovery. This
techniques recover fields with derivatives such as stresses or fluxes with a higher
theoretical convergence than smoothing. Recovery is expensive so it is turned off by
default. The value pprint means that recovery is performed inside domains. The
value ppr means that recovery is also applied on all domain boundaries.
The property Refine constructs evaluation points by making a regular refinements
of each element. Each mesh edge is divided into Refine equal parts.
The property Smooth controls if the post data is forced to be continuous on element
edges. When Smooth is set to internal, only elements not on interior boundaries are
made continuous.
When the property Phase is used, the solution vector is multiplied with
exp(i*phase) before evaluating the expression.

The expressions e1,...,en are evaluated for one or several solutions. Each solution
generates an additional row in the data fields of the post data output structure. The
property Solnum and t control which solutions are used for the evaluations. The
Solnum property is available when the data set has multiple solutions, for example,
in the case of parametric, eigenfrequency, or time-dependent solutions. The t
property is available only for time-dependent problems. If Solnum is provided, the
solutions indicated by the indices provided with the Solnum property are used. If t
is provided solutions are interpolated. If neither Solnum nor t is provided, all
solutions are evaluated.
For time-dependent problems, the variable t can be used in the expressions ei. The
value of t is the interpolation time when the property t is provided, and the time
for the solution, when Solnum is used. Similarly, lambda and the parameter are

231

mphinterp
available as eigenvalues for eigenvalue problems and as parameter values for
parametric problems, respectively.
In case of multiple expression, if the unit property is defined with a string, the same
unit is used for both expressions. To use different units, set the property with a cell
array. In case of inconsistent unit definition, the default unit is used instead.
Solnum is used to select the solution number when a parametric, eigenvalue or
time-dependent solver has been used.
Outersolnum is used to select the outer solution number when a parametric sweep

has been used in the study step node.

Example

Evaluate the temperature at given coordinates:

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
std.feature.create('stat','Stationary');
std.run;
coord = [0,0,1e-2;0,0,1e-2;0,1e-2,1e-2];
T = mphinterp(model,'T','coord',coord);

Evaluate both the temperature and the heat flux magnitude:

[T,tfluxMag] = mphinterp(model,{'T','ht.tfluxMag'},...
'coord',coord);

Evaluate the temperature field on a structure grid:

x0 = [0,1e-2,2.5e-2,5e-2]; y0 = x0; z0 = [5e-3,1e-2,1.1e-2];
[x,y,z] = meshgrid(x0,y0,z0); xx = [x(:),y(:),z(:)]';
T = mphinterp(model,'T','coord',xx);

Evaluate the temperature on boundary 7 using global coordinates:

x0 = [0,5e-3,1e-2]; y0 = x0; z0 = [1.1e-2];
[x,y,z] = meshgrid(x0,y0,z0); xx = [x(:),y(:),z(:)]';
T = mphinterp(model,'T','coord',xx,'edim','boundary',...
'selection',7);

Evaluate the temperature and evaluation point global coordinates on boundary 7

using local coordinates:
s10 = [0,0.25,0.5]; s20 = [0,0.25,0.5];
[s1,s2] = meshgrid(s10,s20); ss = [s1(:),s2(:)]';
[x,y,z,T] = mphinterp(model,{'x','y','z','T'},'coord',ss,...
'edim','boundary','selection',7);

Modify the extrapolation distance for point coordinates outside of the geometry:

232 |

CHAPTER 6: COMMAND REFERENCE

mphinterp
coord = [5e-2;5e-2;1.1e-2];
T = mphinterp(model,'T','coord',coord)
T = mphinterp(model,'T','coord',coord,'ext',0.5);

Extract data using a cut line data set. First create the cutline data set, then evaluate
the temperature field along the line:
cln = model.result.dataset.create('cln', 'CutLine3D');
cln.setIndex('genpoints','1e-2',1,0);
cln.setIndex('genpoints','1e-2',0,2);
cln.setIndex('genpoints','5e-2',1,0);
T = mphinterp(model,'T','dataset','cln');

Evaluation including several solution

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
param = std.feature.create('param','Parametric');
time = std.feature.create('time','Transient');
time.set('tlist', 'range(0,1,25)');
param.setIndex('pname','power',0);
param.setIndex('plistarr','30 60 90',0);
std.run;

Evaluate the temperature at every time step computed with power set to 30:
coord = [0 0 1e-2;0 0 1e-2;0 1e-2 1e-2];
T = mphinterp(model,'T','coord',coord,'dataset','dset2');

Evaluate the temperature at the fifth time step:

T = mphinterp(model,'T','coord',coord,'dataset','dset2',...
'solnum',5);

Evaluate the temperature at 10.5 sec:

T = mphinterp(model,'T','coord',coord,'dataset','dset2',...
't',10.5);

Evaluate the temperature at every time step computed with power set to 90:
T = mphinterp(model,'T','coord',coord,'dataset','dset2',...
'outersolnum',3)
See also

mpheval, mphevalpoint, mphglobal

233

mphload
Load a COMSOL Multiphysics model MPH-file.

Purpose

mphload

Syntax

model =
model =
model =
[model,

Description

model = mphload(filename) loads a COMSOL model object saved with the

name filename and assigns the default name Model in the COMSOL server.

mphload(filename)
mphload(filename, ModelObjectName)
mphload(filename, ModelObjectName, '-history')
filename] = mphload(filename, ModelObjectName)

model = mphload(filename, ModelObjectName) loads a COMSOL model

object and assigns the name ModelObjectName in the COMSOL server.
model = mphload(filename, ModelObjectName, '-history') turns on

history recording.
[model, filenameloaded] = mphload(filename, ModelObjectName) also

returns the full file name filenameloaded of the file that was loaded.
If the model name is the same as a model that is currently in the COMSOL server
the loaded model overwrites the existing one.
Note that MATLAB searches for the model on the MATLAB path if an absolute
path is not supplied.
mphload turns off the model history recording by default, unless the property
'-history' is used.

The extension mph can be omitted.

Example

Load the file model_tutorial_llmatlab.mph:

model = mphload('model_tutorial_llmatlab');

Load the file model_tutorial_llmatlab.mph and set the model name in the
COMSOL server to Model2:
model = mphload('model_tutorial_llmatlab','Model2');

Load MyModel.mph with the path specified:

model = mphload('PATH\MyModel.mph');

Load model_tutorial_llmatlab.mph and return the filename:

[model, filename] = mphload('model_tutorial_llmatlab');
See also

234 |

mphsave

CHAPTER 6: COMMAND REFERENCE

mphmatrix
Get model matrices.

Purpose

mphmatrix

Syntax

str = mphmatrix(model,soltag,'Out',...)

Description

str = mphmatrix(model,soltag,'Out',{'A'},...) returns a MATLAB

structure str containing the matrix A assembled using the solver node soltag and
accessible as str.A. A being taken from the Out property list.
str = mphmatrix(model,soltag,fname,'Out',{'A','B',...}) returns a

MATLAB structure str containing the matrices A, B, ... assembled using the solver
node solname and accessible as str.A and str.B. A and B being taken from the
Out property list.
The function mphmatrix accepts the following property/value pairs:
TABLE 6-12: PROPERTY/VALUE PAIRS FOR THE MPHMATRIX COMMAND
PROPERTY

EXPRESSION

out

Cell array of
strings

DEFAULT

DESCRIPTION

Eigname

String

lambda

Eigenvalue name

Eigref

Double

Value of eigenvalue
linearization point

Initmethod

init | sol

sol

Use linearization point

Initsol

string | zero

Active
solver tag

Solution to use for

linearization

Solnum

Positive
integer| auto

auto

Solution number

Study

Study tag

{First
study}

Study to use with

initmethod

List of matrices to assemble

The following values are valid for the out property:

Property/Value Pairs for the property out.
PROPERTY

EXPRESSION

DESCRIPTION

out

Stiffness matrix

Load vector

Constraint vector

Constraint Jacobian

Damping matrix

Mass matrix

NF

Constraint force Jacobian

235

mphmatrix
Property/Value Pairs for the property out.
PROPERTY

EXPRESSION

DESCRIPTION

NP

Optimization constraint Jacobian (*)

MP

Optimization constraint vector (*)

MLB

Lower bound constraint vector (*)

MUB

Upper bound constraint vector (*)

Kc

Eliminated stiffness matrix

Lc

Eliminated load vector

Dc

Eliminated damping matrix

Ec

Eliminated mass matrix

Null

Constraint null-space basis

Nullf

Constraint force null-space matrix

ud

Particular solution ud

uscale

Scale vector

(*) Requires the Optimization Module.

Note that the assembly of the eliminated matrices uses the current solution vector
as scaling method. To get the unscaled eliminated system matrices, it is required to
set the scaling method to 'none' in the variables step of the solver configuration
node.
The load vector is assembled using the current solution available as linearization
point unless the initmethod property is provided. In case of the presence of a solver
step node in the solver sequence, the load vector correspond then to the residual of
the problem.
Example

Evaluate the system matrices of a stationary problem

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std1');
std.feature.create('stat', 'Stationary');
std.run;

Get the stationary matrix system, use the initial solution as linearization point:
str = mphmatrix(model,'sol1','out',{'K','L','M','N'},...
'initmethod','init');

Display the sparsity of the stiffness matrix and the constraint vector and compute the
total load applied in the matrix system:
subplot(2,1,1); spy(str.K);subplot(2,1,2);spy(str.N)

236 |

CHAPTER 6: COMMAND REFERENCE

mphmatrix
Q = sum(str.L)

Get the eliminated matrix system, use the initial solution as linearization point:
str = mphmatrix(model,'sol1','out',{'Kc'},'initmethod','init');

Compare the sparsity between the eliminated and non-eliminated stiffness matrix:
subplot(2,1,1); hold on; spy(str.Kc,'r')

Evaluate the eliminated load vector using the current solution as linearization point:
str = mphmatrix(model,'sol1','out',{'Lc'},'initmethod','sol');

Evaluate the system matrices of a dynamic problem

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std1');
time = std.feature.create('time', 'Transient');
time.set('tlist', 'range(0,1,25)');
std.run;

Get the dynamic matrix system:

str = mphmatrix(model,'sol1','out',{'E','D','K','L','M','N'});

Display the sparsity of the mass and stiffness matrices:

subplot(1,2,1); spy(str.D); subplot(1,2,2); spy(str.K);

Get the eliminated dynamic matrix system:

str =
mphmatrix(model,'sol1','out',{'Ec','Dc','Kc','Lc','M','N'});

Assemble the Jacobian using solution number 15 as linearization point:

str = mphmatrix(model,'sol1','out',{'K'},...
'initmethod','sol','solnum',15);

Assemble the Jacobian using the zero vector as linearization point:

str = mphmatrix(model,'sol1','out',{'K'},...
'initmethod','sol','initsol','zero');
See also

mphstate, mphxmeshinfo, mphinputmatrix

237

mphmax
Perform maximum of expressions.

Purpose

mphmax

Syntax

[v1,...,vn] = mphmax(model,{e1,...,en},edim,...)
[v1,...,vn,unit] = mphmax(model,{e1,...,en},edim,...)

Description

[v1,...,vn] = mphmax(model,{e1,...,en},edim,...) evaluates the

maximum of the string expressions e1,...,en and returns the result in N matrices
v1,...,vn with M rows and P columns. M is the number of inner solution and P
the number of outer solution used for the evaluation. edim defines the element
dimension: line, surface, volume or as an integer value.
[v1,...,vn] = mphmax(model,{e1,...,en},edim,...) also returns the units

of the maximum in a 1xN cell array.

The function mphmax accepts the following property/value pairs:
TABLE 6-13: PROPERTY/VALUE PAIRS FOR THE MPHMAX COMMAND.
PROPERTY

PROPERTY VALUE

DEFAULT

DESCRIPTION

Dataset

String

active
solution
data set

Data set tag

Matrix

off | on

on

Returns data as a matrix or

as a cell

Outersolnum

Positive integer
array | all |
end

Solution number for

parametric sweep

Selection

Integer vector |
string | all

all

Selection list or named

selection

Solnum

Integer vector |
end | all

all

Solution for evaluation

Squeeze

on | off

on

Squeeze singleton
dimensions

Double array

Time for evaluation

The property Dataset controls which data set is used for the evaluation. Data Sets
contain or refer to the source of data for postprocessing purposes. Evaluation is
supported only on Solution Data Sets.
The maximum expressions e1,...,en is evaluated for one or several solutions.
Each solution generates an additional column in the returned matrix. The property
Solnum and t control which solutions are used for the evaluation. The Solnum
property is available when the data set has multiple solutions, for example in the case
of parametric, eigenfrequency, or time-dependent solutions. The t property is

238 |

CHAPTER 6: COMMAND REFERENCE

mphmax
available only for time-dependent problems. If Solnum is provided, the solutions
indicated by the indices provided with the Solnum property are used. If t is provided
solutions are interpolated. If neither Solnum nor t is provided, all solutions are
evaluated.
Solnum is used to select the solution number when a parametric, eigenvalue or

time-dependent solver has been used.

Outersolnum is used to select the outer solution number when a parametric sweep

has been used in the study step node.

If the Matrix property is set to off the output is cell arrays of length P containing
cell arrays of length M.
Example

Evaluate the maximum temperature in the model domain:

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
std.feature.create('stat','Stationary');
std.run;
maxT = mphmax(model,'T','volume');

Evaluate the maximum temperature on boundary 9:

maxT = mphmax(model,'T','surface','selection',9);

Evaluate maximum of expression using several solution:

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
param = std.feature.create('param','Parametric');
time = std.feature.create('time','Transient');
time.set('tlist', 'range(0,1,25)');
param.setIndex('pname','power',0);
param.setIndex('plistarr','30 60 90',0);
std.run;

Evaluate the maximum of the temperature at every time step computed with power
set to 30:
maxT = mphmax(model,'T','volume','dataset','dset2');

Evaluate the maximum of the temperature at the fifth time step:

maxT = mphmax(model,'T','volume','dataset','dset2',...
'solnum',5);

Evaluate the maximum of the temperature at 10.5 sec and 15.2 sec:

239

mphmax
maxT = mphmax(model,'T','volume','dataset','dset2',...
't',[10.5,15.2]);

Evaluate the maximum of the temperature at every time step computed with power
set to 90:
maxT = mphmax(model,'T','volume','dataset','dset2',....
'outersolnum',3);
See also

240 |

CHAPTER 6: COMMAND REFERENCE

mphmean, mphmin

mphmean
Perform mean of expressions.

Purpose

mphmean

Syntax

[v1,...,vn] = mphmean(model,{e1,...,en},edim,...)
[v1,...,vn,unit] = mphmean(model,{e1,...,en},edim,...)

Description

[v1,...,vn] = mphmean(model,{e1,...,en},edim,...) evaluates the means

of the string expressions e1,...,en and returns the result in N matrices v1,...,vn
with M rows and P columns. M is the number of inner solution and P the number
of outer solution used for the evaluation. edim defines the element dimension:
line, surface, volume or as an integer value.
[v1,...,vn] = mphmean(model,{e1,...,en},edim,...) also returns the units

of the maximum in a 1xN cell array.

The function mphmean accepts the following property/value pairs:
TABLE 6-14: PROPERTY/VALUE PAIRS FOR THE MPHMEAN COMMAND.
PROPERTY

PROPERTY VALUE

DEFAULT

DESCRIPTION

Dataset

String

active
solution
data set

Data set tag

Intorder

Positive integer

Integration order

Matrix

off | on

on

Returns data as a matrix or

as a cell

Method

auto |
integration |
summation

auto

Integration method

Outersolnum

Positive integer
array | all |
end

Solution number for

parametric sweep

Selection

Integer vector |
string | all

all

Selection list or named

selection

Solnum

Integer vector |
end | all

all

Solution for evaluation

Squeeze

on | off

on

Squeeze singleton
dimensions

Double array

Time for evaluation

The property Dataset controls which data set is used for the evaluation. Data Sets
contain or refer to the source of data for postprocessing purposes. Evaluation is
supported only on Solution Data Sets.

241

mphmean
The mean of expressions e1,...,en is evaluated for one or several solutions. Each
solution generates an additional column in the returned matrix. The property
Solnum and t control which solutions are used for the evaluation. The Solnum
property is available when the data set has multiple solutions, for example in the case
of parametric, eigenfrequency, or time-dependent solutions. The t property is
available only for time-dependent problems. If Solnum is provided, the solutions
indicated by the indices provided with the Solnum property are used. If t is provided
solutions are interpolated. If neither Solnum nor t is provided, all solutions are
evaluated.
Solnum is used to select the solution number when a parametric, eigenvalue or
time-dependent solver has been used.
Outersolnum is used to select the outer solution number when a parametric sweep

has been used in the study step node.

If the Matrix property is set to off the output is cell arrays of length P containing
cell arrays of length M.
Example

Evaluate the mean temperature in the model domain:

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
std.feature.create('stat','Stationary');
std.run;
maxT = mphmean(model,'T','volume');

Evaluate the mean temperature on boundary 9:

maxT = mphmean(model,'T','surface','selection',9);

Evaluate mean of expression using several solution:

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
param = std.feature.create('param','Parametric');
time = std.feature.create('time','Transient');
time.set('tlist', 'range(0,1,25)');
param.setIndex('pname','power',0);
param.setIndex('plistarr','30 60 90',0);
std.run;

Evaluate the mean of the temperature at every time step computed with power set
to 30:

242 |

CHAPTER 6: COMMAND REFERENCE

mphmean
maxT = mphmean(model,'T','volume','dataset','dset2');

Evaluate the mean of the temperature at the fifth time step:

maxT = mphmean(model,'T','volume','dataset','dset2',...
'solnum',5);

Evaluate the mean of the temperature at 10.5 sec and 15.2 sec:
maxT = mphmean(model,'T','volume','dataset','dset2',...
't',[10.5,15.2]);

Evaluate the mean of the temperature at every time step computed with power set
to 90:
maxT = mphmean(model,'T','volume','dataset','dset2',....

'outersolnum',3);
See also

mphmax, mphmin

243

mphmesh
Plot a mesh in a MATLAB figure window.

Purpose

mphmesh

Syntax

mphmesh(model)
mphmesh(model,meshtag,...)

Description

mphmesh(model) plots the mesh case in a MATLAB figure.

mphmesh(model,meshtag,...) plots the mesh case meshtag in a MATLAB

figure.
The function mphmesh accepts the following property/value pairs:
TABLE 6-15: PROPERTY/VALUE PAIRS FOR THE MPHMESH COMMAND

Example

PROPERTY

VALUE

DEFAULT

DESCRIPTION

Parent

Double

Edgecolor

Char

Edge color

Edgelabels

on | off

off

Show edge labels

Edgelabelscolor

Char

Color for edge labels

Edgemode

on | off

on

Show edges

Facealpha

Double

Set transparency value

Facelabels

on | off

off

Show face labels

Facelabelscolor

Char

Color for face labels

Facemode

on | off

on

Show faces

Parent axis

Meshcolor

Char

flat

Color for face element

Vertexlabels

on | off

off

Show vertex labels

Vertexlabelscolor

Char

Color for vertex labels

Vertexmode

on | off

off

Show vertices

Plot the mesh case

model = mphload('model_tutorial_llmatlab');
model.mesh.run;
mphmesh(model)

Create a second mesh case with an extra fine default mesh settings and plot it:
mesh = model.mesh.create('mesh2', 'geom1');
mesh.autoMeshSize(2);
mesh.run;
mphmesh(model,'mesh2','meshcolor','r');
See also

244 |

CHAPTER 6: COMMAND REFERENCE

mphgeom, mphmeshstats, mphplot

mphmeshstats
Return mesh statistics and mesh data information

Purpose

mphmeshstats

Syntax

stats = mphmeshstats(model)
stats = mphmeshstats(model, meshtag)
[stats,data] = mphmeshstats(model, meshtag)

Description

stats = mphmeshstats(model) returns mesh statistics of the model mesh case in

the structure str.

stats = mphmeshstats(model, meshtag) returns mesh statistics of a mesh case
meshtag in the structure str.
[stats,data] = mphmeshstats(model, meshtag) returns in addition the mesh

data information such as vertex coordinates and definitions of elements in the

structure data.
The output structure stats contains the following fields:
TABLE 6-16: FIELDS IN THE STATS STRUCTURE
FIELD

DESCRIPTION

Meshtag

Mesh case tag

Geomtag

Associated geometry tag

Isactive

Is the mesh node active

Hasproblems

Does the mesh have problems?

Iscomplete

Is the mesh built to completion?

Sdim

Space dimension

Types

Cell array with type names

Numelem

Vector with the number of elements for each type

Minquality

Minimum quality

Meanquality

Mean quality

Qualitydistr

Quality distribution (vector)

Minvolume

Volume/area of the smallest element

Maxvolume

Volume/area of the largest element

Volume

Volume/area of the mesh

245

mphmeshstats
The output structure data contains the following fields:
TABLE 6-17: FIELDS IN THE DATA STRUCTURE

Example

FIELD

DESCRIPTOIN

Vertex

Coordinates of mesh vertices

Elem

Cell array of definition of each element type

Elementity

Entity information for each element type

Get the mesh statistics:

model = mphload('model_tutorial_llmatlab');
model.mesh.run;
stats = mphmeshstats(model)

Show the mesh quality distribution in a figure:

bar(linspace(0,1,20),stats.qualitydistr)

Get the mesh statistics and the mesh data:

[stats,data] = mphmeshstats(model);

Show the element vertices in a plot:

plot3(data.vertex(1,:), data.vertex(2,:), data.vertex(3,:), '.')
axis equal

Get the number of edge element:

numedgeelem = stats.numelem(strcmp(stats.types,'edg'))
See also

246 |

CHAPTER 6: COMMAND REFERENCE

mphmesh

mphmin
Perform minimum of expressions.

Purpose

mphmin

Syntax

[v1,...,vn] = mphmin(model,{e1,...,en},edim,...)
[v1,...,vn,unit] = mphmin(model,{e1,...,en},edim,...)

Description

[v1,...,vn] = mphmin(model,{e1,...,en},edim,...) evaluates the

minimum of the string expressions e1,...,en and returns the result in N matrices
v1,...,vn with M rows and P columns. M is the number of inner solution and P

the number of outer solution used for the evaluation. edim defines the element
dimension: line, surface, volume or as an integer value.
[v1,...,vn] = mphmin(model,{e1,...,en},edim,...) also returns the units

in a 1xN cell array.

The function mphmin accepts the following property/value pairs:
TABLE 6-18: PROPERTY/VALUE PAIRS FOR THE MPHMIN COMMAND.
PROPERTY

PROPERTY VALUE

DEFAULT

DESCRIPTION

Dataset

String

active
solution
data set

Data set tag

Matrix

off | on

on

Returns data as a matrix or

as a cell

Outersolnum

Positive integer
array | all |
end

Solution number for

parametric sweep

Selection

Integer vector |
string | all

all

Selection list or named

selection

Solnum

Integer vector |
end | all

all

Solution for evaluation

Squeeze

on | off

on

Squeeze singleton
dimensions

Double array

Time for evaluation

The property Dataset controls which data set is used for the evaluation. Data Sets
contain or refer to the source of data for postprocessing purposes. Evaluation is
supported only on Solution Data Sets.
The mean of expressions e1,...,en is evaluated for one or several solutions. Each
solution generates an additional column in the returned matrix. The property
Solnum and t control which solutions are used for the evaluation. The Solnum
property is available when the data set has multiple solutions, for example in the case
of parametric, eigenfrequency, or time-dependent solutions. The t property is

247

mphmin
available only for time-dependent problems. If Solnum is provided, the solutions
indicated by the indices provided with the Solnum property are used. If t is provided
solutions are interpolated. If neither Solnum nor t is provided, all solutions are
evaluated.
Solnum is used to select the solution number when a parametric, eigenvalue or

time-dependent solver has been used.

Outersolnum is used to select the outer solution number when a parametric sweep

has been used in the study step node.

If the Matrix property is set to off the output is cell arrays of length P containing
cell arrays of length M.
Example

Evaluate the minimum temperature in the model domain:

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
std.feature.create('stat','Stationary');
std.run;
maxT = mphmin(model,'T','volume');

Evaluate the minimum temperature on boundary 9:

maxT = mphmin(model,'T','surface','selection',9);

Evaluate minimum of expression using several solution:

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
param = std.feature.create('param','Parametric');
time = std.feature.create('time','Transient');
time.set('tlist', 'range(0,1,25)');
param.setIndex('pname','power',0);
param.setIndex('plistarr','30 60 90',0);
std.run;

Evaluate the minimum of the temperature at every time step computed with power
set to 30:
maxT = mphmin(model,'T','volume','dataset','dset2');

Evaluate the minimum of the temperature at the fifth time step:

maxT = mphmin(model,'T','volume','dataset','dset2',...
'solnum',5);

Evaluate the minimum of the temperature at 10.5 sec and 15.2 sec:

248 |

CHAPTER 6: COMMAND REFERENCE

mphmin
maxT = mphmin(model,'T','volume','dataset','dset2',...
't',[10.5,15.2]);

Evaluate the minimum of the temperature at every time step computed with power
set to 90:
maxT = mphmin(model,'T','volume','dataset','dset2',....

'outersolnum',3);
See also

mphmax, mphmean

249

mphmodel
Return tags for the nodes and subnodes in the COMSOL model object.

Purpose

mphmodel

Syntax

mphmodel(model)
str = mphmodel(model,'-struct')

Description

mphmodel(model) returns the tags for the nodes and subnodes of the object model.
str = mphmodel(model,'-struct') returns the tags for the nodes and subnodes
of the object model as a MATLAB structure str.

The function mphmodel can be used when navigating the model object and learning
about its structure. The mphmodel function is mainly designed for usage when
working on the command line and one needs to learn what nodes are placed under
a particular node.
Example

Load the model busbar.mph and get the list of the nodes available under the root
node:
model = mphload('busbar')
mphmodel(model)

See what nodes are available under the geometry node:

mphmodel(model.geom)

Get the model information as a structure:

res = mphmodel(model, '-struct')
See also

250 |

mphnavigator, mphsearch

CHAPTER 6: COMMAND REFERENCE

mphmodellibrary
Graphical User Interface for viewing the Model Libraries.

Purpose

mphmodellibrary

Syntax

mphmodellibrary

Description

mphmodellibrary starts a GUI to visualize and access the example model available

in the COMSOL Multiphysics Model Libraries. The model MPH-file can be loaded
in MATLAB and the model documentation PDF-file is accessible directly. Models
that are specific to LiveLink for MATLAB also contains the script M-file.

251

mphnavigator
Graphical User Interface for viewing the COMSOL Multiphysics model object

Purpose

mphnavigator

Syntax

mphnavigator
mphnavigator(modelvariable)

Description

mphnavigator opens the Model Object Navigator which is a graphical user

interface that can be used to navigate the model object and to view the properties
and methods of the nodes in the model tree.
The GUI requires that the COMSOL objest is stored in a variable in the base
workspace (at the MATLAB command prompt) with the name model.
mphnavigator(modelvariable) opens the model object defined with the name
modelvariable in Model Object Navigator.

Example

Load busbar.mph from the model library:

model = mphload('busbar')

Navigate the model object that is accessible with the variable model
mphnavigator

252 |

CHAPTER 6: COMMAND REFERENCE

mphnavigator
Load effective_diffusivity.mph from the model library and set the model
object with the variable eff_diff:
eff_diff = mphload('effective_diffusivity');

Navigate the model object that is accessible with the variable eff_diff
mphnavigator(eff_diff)
See also

mphgetexpressions, mphgetproperties, mphgetselection, mphmodel,

mphsearch

253

mphparticle
Evaluate expressions on particle trajectories

Purpose

mphparticle

Syntax

pd = mphparticle(model)
pd = mphparticle(model,'expr',{e1,...,en},...)

Description

mphparticle(model) returns particle position and particle velocity at all time steps
stored in the first particle dataset.
mphparticle(model,'expr',{e1,...,en},...) returns particle position,
particle velocity and expressions e1, ..., en evaluated on particle trajectories.

The function mphparticle accepts the following property/value pairs:

TABLE 6-19: PROPERTY/VALUE PAIRS FOR THE MPHPARTICLE COMMAND
PROPERTY

VALUE

Expr

String |
String cell
array

DEFAULT

DESCRIPTION

Dataonly

on | off

off

Return only expression values

Dataset

String

First
particle
dataset

Data set tag

Double array

Expressions to evaluate

Time for evaluation

The returned value pd is a structure with the following content

TABLE 6-20: FIELDS IN THE INFO STRUCT
FIELD

CONTENT

Velocity of the particles

Position of the particles

d#

Result of evaluation #

Time for evaluation

expr

Evaluated expressions

unit

Unit of evaluations

Note: mphparticle requires a particle dataset generated with the Particle Tracing
Module.

Example

254 |

Load the model laminar_mixer_particle from the model library:

CHAPTER 6: COMMAND REFERENCE

mphparticle
model = mphload('laminar_mixer_particle');

Extract the particle positions and particle velocities along the computed trajectories
at every time steps stored in the model:
pd = mphparticle(model)

Evaluate the fluid pressure and fluid velocity magnitude value along the particle
trajectories at t=2.65 sec., extract only the data:
pd = mphparticle(model,'expr',{'p','spf.U'},'t',2.65,...
'dataonly','on')
See also

mpheval, mphevalpoint, mphint2, mphinterp

255

mphplot
Render a plot group in a figure window.

Purpose

mphplot

Syntax

mphplot(model,pgtag,...)
pd = mphplot(model,pgtag,...)
mphplot(pd,...)

Description

mphplot(model,pgtag,...) renders the plot group tagged pgtag from the

model object model in a figure window in MATLAB.
pd = mphplot(model,pgtag,...) also returns the plot data used in the MATLAB

figure in a cell array pd.

mphplot(pd,...) makes a plot using the post data structure pd that is generated

using the function mpheval. Plots involving points, lines and surfaces are supported.
The function mphplot accepts the following property/value pairs:
TABLE 6-21: PROPERTY/VALUE PAIRS FOR THE MPHPLOT COMMAND
PROPERTY

VALUE

DEFAULT

DESCRIPTION

Colortable

String

Rainbow

Color table used for plotting

post data structure

Index

Positive
integer

Index of variable to use plotting

post data structure

Mesh

on | off

on

Plot the mesh when using post

data structure

Parent

Double

Rangenum

Positive
Integer

none

Color range bar (or legend) to

display

Server

on | off

off

Plot on server

Set the parent axes

Note: The plot on server option requires that you start COMSOL with MATLAB
in graphics mode.

Only one color range bar and one legend bar is supported in a MATLAB figure.
When the option plot on server is active, all active color range bar are displayed.
Example

Display the plot settings pg using a MATLAB figure

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
std.feature.create('stat','Stationary');

256 |

CHAPTER 6: COMMAND REFERENCE

mphplot
std.run;
model.result.dataset.create('mir', 'Mirror3D');
pg = model.result.create('pg', 'PlotGroup3D');
pg.set('data', 'mir');
surf1 = pg.feature.create('surf1', 'Surface');
surf1.set('colortable', 'Thermal');
mphplot(model,'pg')

Combine plot types on the same plot group:

surf2 = pg.feature.create('surf2', 'Surface');
surf2.set('data', 'dset1');
surf2.set('expr', 'ht.tfluxMag');

Display the plot group and the color range bar of the second plot type:
mphplot(model,'pg','rangenum',2)

Display the plot group on the server:

mphplot(model,'pg','server','on')

% Display expression value evaluated using mpheval:

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
std.feature.create('stat','Stationary');
std.run;

Extract temperature and total heat flux magnitude in domain 2:

pd = mpheval(model,{'T','ht.tfluxMag'},'selection',2);

Plot the temperature data using thermal color table:

mphplot(pd,'index',1,'colortable','Thermal','rangenum',1)
See also

colortable, mpheval

257

mphsave
Save a COMSOL Multiphysics model

Purpose

mphsave

Syntax

mphsave(model)
mphsave(model, filename)

Description

mphsave(model) saves the COMSOL model object model.

mphsave(model, filename) saves the COMSOL model object model to the file
named filename.

If the file name is not provided, the model has to be saved previously on disk.
If the file name does not provide a path, the file is saved relatively to the current path
in MATLAB.
The model can be saved as an MPH-file, Java file, or M-file. The file extension
determines which format that is saved.
See also

258 |

mphload

CHAPTER 6: COMMAND REFERENCE

mphsearch
GUI for searching expressions in the COMSOL Multiphysics model object

Purpose

mphsearch

Syntax

mphsearch(model)

Description

mphsearch(model) opens a graphical user interface that can be used to search

expressions in the model object model. Search using a text available in the name,
expression or description of the variable.

See also

mphgetexpressions, mphnavigator

259

mphselectbox
Select geometric entity using a rubberband/box.

Purpose

mphselectbox

Syntax

n = mphselectbox(model,geomtag,boxcoord,entity,...)

Description

n = mphselectbox(model,geomtag,boxcoord,entity,...) returns the indices

of the geometry entities that are inside a selection domain (rectangle or box). This
method looks only on the vertex coordinates and does not observe all points on
curves and surfaces.
boxcoord set the coordinates of the selection domain, specified as a Nx2 array,

where N is the geometry space dimension.

entity can be one of 'point', 'edge', 'boundary' or 'domain' following the

entity space dimension defined below:

'domain': maximum geometry space dimension

'boundary': maximum geometry space dimension -1

'edges': 1(only for 3D geometry)

The function mphpselectbox accepts the following property/value pairs:

TABLE 6-22: PROPERTY/VALUE PAIRS FOR THE MPHSELECTBOX COMMAND
PROPERTY

VALUE

DEFAULT

DESCRIPTION

Adjnumber

Scalar

none

Adjacent entity number

When a model uses form an assembly more than one vertex can have the same
coordinate if the coordinate is shared by separate geometric objects. In that case one
can use the adjnumber property in order to identify the domain that the vertices
should be adjacent to.
Example

Find the domains using a box selection:

model = mphload('model_tutorial_llmatlab');
coordBox = [-1e-3 11e-3;-1e-3 11e-3;9e-3 11e-3];
n = mphselectbox(model,'geom1',coordBox,'domain');

Find the boundaries inside the selection box:

n = mphselectbox(model,'geom1',coordBox,'boundary');

Find the boundaries inside the selection box that are adjacent to domain number 1:
n = mphselectbox(model,'geom1',coordBox,'boundary',...
'adjnumber',1);

260 |

CHAPTER 6: COMMAND REFERENCE

mphselectbox
Find geometry entity number in an assembly
model = mphload('model_tutorial_llmatlab');
geom = model.geom('geom1');
geom.feature('fin').set('action','assembly');
geom.run('fin');

Find the boundaries within a box:

coordBox = [-1e-3,51e-3;-1e-3,51e-3;9e-3,11e-3];
n = mphselectbox(model,'geom1',coordBox,'boundary');

Find the boundary adjacent to domain 2:

n = mphselectbox(model,'geom1',coordBox,'boundary',...
'adjnumber',2);
See also

mphgetadj, mphgetcoords, mphselectcoords

261

mphselectcoords
Select geometric entity using point coordinates

Purpose

mphselectcoords

Syntax

n = mphselectcoords(model,geomtag,coord,entity,...)

Description

n = mphselectcoords(model,geomtag,coord,entity,...) finds geometry

entity numbers based on their vertex coordinates.

One or more coordinates can be provided. The function searches for vertices near
these coordinates using a tolerance radius. The list of the entities that are adjacent
to such vertices is returned.
Coord is a NxM array where N correspond of the number of point to use and M the

space dimension of the geometry.

Entity can be one of 'point', 'edge', 'boundary' or 'domain' following the

entity space dimension defined below:

'domain': maximum geometry space dimension

'boundary': maximum geometry space dimension -1

'edges': 1(only for 3D geometry)

The function mphpselectcoords accepts the following property/value pairs:

TABLE 6-23: PROPERTY/VALUE PAIRS FOR THE MPHSELECTCOORDS COMMAND
PROPERTY

VALUE

DEFAULT

DESCRIPTION

Adjnumber

Scalar

none

Adjacent entity number

Radius

Scalar

auto

Search radius

Include

all | any

all

Include all or any vertices

When a model uses form an assembly more than one vertex can have the same
coordinate if the coordinate is shared by separate geometric objects. In that case one
can use the adjnumber property in order to identify the domain that the vertices
should be adjacent to.
The radius property is used to specify the radius of the sphere/circle that the
search should be within. A small positive radius (based on the geometry size) is used
by default in order to compensate for rounding errors.
Use the property include when two point coordinates are used. Set it to all to
select objects within the search radius of all points. any returns objects within the
search radius of any points.
Examplee

262 |

Find geometry entity number

CHAPTER 6: COMMAND REFERENCE

mphselectcoords
model = mphload('model_tutorial_llmatlab');
coord = [10e-3 0 10e-3;0 10e-3 10e-3];

n = mphselectcoords(model,'geom1',coord','point')

Return the indices of the point at coordinates within a search radius of 0.011:
n = mphselectcoords(model,'geom1',coord','point',...
'radius',0.011)

Return the indices of the boundaries that have a vertex within the search radius:
n = mphselectcoords(model,'geom1',coord','boundary',...
'radius',11e-3)

Return the indices of the edges that have a vertex within the search radius from all
points:
coord = [5e-3 0 10e-3;0 5e-3 10e-3];
n = mphselectcoords(model,'geom1',coord','edge',...
'radius',6e-3);

Return the indices of the edges that have a vertex within the search radius from at
least one point:
n = mphselectcoords(model,'geom1',coord','edge',...
'radius',6e-3,'include','any');

Find geometry entity index in an assembly

model = mphload('model_tutorial_llmatlab');
geom = model.geom('geom1');
geom.feature('fin').set('action', 'assembly');
geom.run('fin');

Return the indices of the boundaries that have any vertices within the search range
of a point:
coord = [0,0,10e-3];
n0 = mphselectcoords(model,'geom1',coord,'boundary')

Return the indices of the boundaries that also are adjacent to domain 1:
n1 = mphselectcoords(model,'geom1',coord,'boundary',...
'adjnumber',1);

Return the indices of the boundaries that also are adjacent to domain 2:
n1 = mphselectcoords(model,'geom1',coord,'boundary',...
'adjnumber',2);
See also

mphgetadj, mphgetcoords, mphselectbox

263

mphshowerrors
Show messages in error nodes in the COMSOL Multiphysics model

Purpose

mphshowerrors

Syntax

mphshowerrors(model)
list = mphshowerrors(model)

Description

mphshowerrors(model) shows the error and warning messages stored in the model

and where they are located. The output is displayed in the command window.
list = mphshowerrors(model) returns the error and warning messages stored in

the model and where they are located in the Nx2 cell array list. N corresponding to
the number of errors or warning found in the model object. The first column
contains the node of the error and the second column contain the error message.
See also

264 |

mphnavigator

CHAPTER 6: COMMAND REFERENCE

mphsolinfo
Get information about a solution object

Purpose

mphsolinfo

Syntax

info = mphsolinfo(model,...)
info = mphsolinfo(model,'solname',soltag,...)

Description

info = mphsolinfo(model,...) returns information about the default solution

object.
info = mphsolinfo(model,'solname',soltag,...) returns information about

the solution object soltag.

The function mphsolinfo accepts the following property/value pairs:
TABLE 6-24: PROPERTY VALUE PAIRS FOR THE MPHSOLINFO COMMAND
PROPERTY

VALUE

DEFAULT

DESCRIPTION

Solname

String

Active solution
object

Solution object tag

Dataset

String

Active
solution data
set

Data set tag

NU

on | off

off

Get info about number

of solutions

The returned value info is a structure with the following content

TABLE 6-25: FIELDS IN THE INFO STRUCT
FIELD

CONTENT

Solname

Solution name

Size

Size of the solution vector

Nummesh

Number of meshes in the solution (for automatic

remeshing)

Sizes

Size of the solution vector for each mesh and number of

timesteps/parameters for each mesh

Soltype

Solver type (Stationary, Parametric, Time or Eigenvalue)

Solpar

Name of the parameter

Sizesolvals

Length of the parameter list

Solvals

Values of the parameters, eigenvalues or timesteps

Paramsweepnames

Parametric sweep parameter names

Paramsweepvals

Parametric sweep parameter values

NUsol

Number of solution vectors stored

NUreacf

Number of reaction forces vectors stored

265

mphsolinfo

TABLE 6-25: FIELDS IN THE INFO STRUCT

FIELD

CONTENT

NUadj

Number of adjacency vectors stored

NUfsens

Number of functional sensitivity vectors stored

NUsens

Number of forward sensitivity vectors stored

You can use the function mphgetu to obtain the actual values of the solution vector.
Note that these functions are low level functions and you most often would use
functions such as mphinterp and mpheval to extract numerical data from a model.
Examplee

Get the information about the default solution object:

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
std.feature.create('stat','Stationary');
std.run;
solinfo = mphsolinfo(model)

Get information of multiple solver solution:

model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
param = std.feature.create('param','Parametric');
time = std.feature.create('time','Transient');
time.set('tlist', 'range(0,1,25)');
param.setIndex('pname','power',0);
param.setIndex('plistarr','30 60 90',0);
std.run;

Get the information about the 1st outer solution (power = 30):
solinfo = mphsolinfo(model,'soltag','sol3');

Get the solution vector for 2nd outer solution (power = 60):
solinfo = mphsolinfo(model,'soltag','sol4');
See also

266 |

mphgetu, mphxmeshinfo, mphsolutioninfo

CHAPTER 6: COMMAND REFERENCE

mphsolutioninfo
Get information about solution objects and datasets containing given parameters

Purpose

mphsolutioninfo

Syntax

info = mphsolutioninfo(model)
info = mphsolutioninfo(model,'parameters',{{ei,vi,toli},...},...)

Description

info = mphsolutioninfo(model) returns information about all solution object

and solution dataset combinations in model.

info = mphsolutioninfo(model,'parameters',{{ei,vi,toli}, ...},
...) returns information about solution object and solution dataset containing the
given inner/outer solution parameters ei with the value equal to vi within the
tolerance toli.

The function mphsolutioninfo accepts the following property/value pairs:

TABLE 6-26: PROPERTY VALUE PAIRS FOR THE MPHSOLUTIONINFO COMMAND
PROPERTY

VALUE

DEFAULT

DESCRIPTION

Cellmap

off | onn

off

Set to return a cell version of

the map with headers

Dataset

String

Data set tag

Parameters

Cell | Cell
array

Filter parameters, values and

tolerances

Soltag

String |
String cell
array

Solver node tag

Sort

String |
Scalar | auto

auto

Sort the map by column number

or header tag

The returned value info is a structure with the following content

TABLE 6-27: FIELDS IN THE INFO STRUCT
FIELD

CONTENT

Solutions

List of matched solution tags

Sol#

Substructure containing information related to solution

number #

The substructure info.sol# has the following content

TABLE 6-28: FIELDS IN THE INFO.SOL# SUBSTRUCT
FIELD

CONTENT

Dataset

Tag of the solution data set

Study

Tag of the study associated to the solution

Sequencetype

Type of solution node

267

mphsolutioninfo

TABLE 6-28: FIELDS IN THE INFO.SOL# SUBSTRUCT

Example

FIELD

CONTENT

cellmap

Cellmap describing the connections between parameters

and inner/outer solution numbers

values

Parameters values used in the solution

parameters

Parameters names used in the solution

mapheaders

Headers for the map

map

Map describing the connections between parameters and

inner/outer solution numbers

Load model_tutorial_llmatlab.mph:
model = mphload('model_tutorial_llmatlab');

Create a study combining a parametric sweep and a transient study step:

std = model.study.create('std');
param = std.feature.create('param','Parametric');
time = std.feature.create('time','Transient');

Set the time stepping and the parametric sweep parameters:

time.set('tlist', 'range(0,1,25)');
param.setIndex('pname','power',0);
param.setIndex('plistarr','30 60 90', 0);

Run the study:

std.run;

Retrieve the solution information corresponding to power = 30W:

info = mphsolutioninfo(model,'parameters',{'power',30,0})

Retrieve the solution information corresponding to power = 90 W and around

t = 10.4 sec. and its associated solution data set:
info = mphsolutioninfo(model,'parameters',{{'power',90,0},...
{'t',10.4,0.5}})

Get the solution solution data set associated:

dset = info.sol2.dataset

Get the inner and outer solution number:

solnum = info.sol2.map(end-1)
outersolnum = info.sol2.map(end)
See also

268 |

mphgetu, mphxmeshinfo, mphsolinfo

CHAPTER 6: COMMAND REFERENCE

mphstart
Connect MATLAB to a COMSOL server.

Purpose

mphstart

Syntax

mphstart
mphstart(port)
mphstart(ipaddress,
mphstart(ipaddress,
mphstart(ipaddress,
mphstart(ipaddress,

Description

port)
port, username, password)
port, comsolpath)
port, comsolpath, username, password)

mphstart creates a connection with a COMSOL server using the default port
number (which is 2036).
mphstart(port) creates a connection with a COMSOL server using the specified
port number port.
mphstart(ipaddress, port) creates a connection with a COMSOL server using

the specified IP address ipaddress and the port number port. This command
assumes that the client and the server machine share the same login properties.
mphstart(ipaddress, port, username, password) creates a connection with
a COMSOL server using the specified IP address ipaddress and the port number
port, the username username and password password.
mphstart(ipaddress, port, comsolpath) creates a connection with a

COMSOL server using the specified IP address and port number using the
comsolpath that is specified. This is useful if mphstart cannot find the location of
the COMSOL Multiphysics installation.
mphstart(ipaddress, port, comsolpath, username, password) creates a
connection with a COMSOL server using the specified IP address, the port
number, the username and password using the comsolpath that is specified. This
is useful if mphstart cannot find the location of the COMSOL Multiphysics
installation.
mphstart can be used to create a connection from within MATLAB when this is
started without using the COMSOL with MATLAB option. mphstart then sets up
the necessary environment and connect to COMSOL.

Prior to calling mphstart it is necessary to set the path of mphstart.m in the

MATLAB path or to change the current directory in MATLAB (for example, using
the cd command) to the location of the mphstart.m file.
A COMSOL server must be started prior to running mphstart.

269

mphstate
Get state-space matrices for dynamic system.

Purpose

mphstate

Syntax

str = mphstate(model,soltag,'Out',{'SP'})
str = mphstate(model,soltag,'Out',{'SP1','SP2',...})

Description

str = mphstate(model,soltag,'out',{'SP'}) returns a MATLAB

structure

str containing the state space matrix SP assembled using the solver node soltag

and accessible as str.SP. SP being taken from the Out property list.
str = mphstate(model,soltag,'Out',{'SP1','SP2',...}) returns a
MATLAB structure str containing the state space matrices SP1, SP2,... assembled
using the solver node soltag and accessible as str.SP1and str.SP2. SP1 and SP2
being taken from the Out property list.

The function mphstate accepts the following property/value pairs:

TABLE 6-29: PROPERTY VALUE FOR THE MPHSTATE COMMAND
PROPERTY

VALUE

DEFAULT

DESCRIPTION

Out

MA | MB | A | B |
C | D |Mc |Null |
ud | x0

Keepfeature

off | on

Input

String

Output

String

Sparse

off | on

Initmethod

init | sol

Initsol

solname | zero

solname

Solution to use for

linearization

Solnum

Positive integer

auto

Solution number

Output matrix

off

Keep the state-space feature in

the model
Input variables
Output variables

off

Return sparse matrices

Use linearization point

The property Sparse controls whether the matrices A, B, C, D, M, MA, MB, and Null
are stored in the sparse format.
The equations correspond to the system below:
Mcx = McAx + McBu

y = Cx + Du

where x are the state variables, u are the input variables, and y are the output
variables.

270 |

CHAPTER 6: COMMAND REFERENCE

mphstate
A static linearized model of the system can be described by:
y = D C McA 1 McB u
The full solution vector U can be then obtained from
U = Nullx + ud + u0
where Null is the null space matrix, ud the constraint contribution and u0 is the
linearization point, which is the solution stored in the sequence once the state space
export feature is run.
The matrices Mc and MA are produced by the same algorithms that do the
finite-element assembly and constraint elimination in COMSOL Multiphysics. Mc
and MA are the same as the matrices Dc (eliminated mass matrix) and Kc (Kc is the
eliminated stiffness matrix). The matrices are produced from an exact residual vector
Jacobian calculation (that is, differentiation of the residual vector with respect to the
degrees of freedoms x) plus an algebraic elimination of the constraints. The matrix
C is produced in a similar way; that is, the exact output vector Jacobian matrix plus
constraint elimination.
The matrices MB and D are produced by a numerical differentiation of the residual
and output vectors, respectively, with respect to the input parameters (the algorithm
systematically perturbs the input parameters by multiplying them by a factor
(1+10-8)).
The input cannot be a variable constraint in the model.
Example

Load model_tutorial_llmatlab.mph:
model = mphload('model_tutorial_llmatlab');
model.mesh('mesh1').autoMeshSize(9);
std = model.study.create('std');
time = std.feature.create('time','Transient');
time.set('tlist','range(0,1,50)');
std.run;

Add a domain point probe plot:

pdom = model.probe.create('pdom', 'DomainPoint');
pdom.model('comp1');
pdom.setIndex('coords3','1e-2',0,0);
pdom.setIndex('coords3','1e-2',0,1);
pdom.setIndex('coords3','0.5e-2',0,2);

Extract the matrices of the following state-space system:

271

mphstate
M = mphstate(model,'sol1','out',{'A','B','C','D'},...
'input','power','output','comp1.ppb1');

Plot the sparsity of the matrix A:

subplot(1,2,1); spy(M.A); subplot(1,2,2); spy(abs(M.A)>1e-2)

Set the input power parameter and the reference temperature:

power = 30; T0 = 300;

Compute the system solution:

func = @(t,x) M.A*x + M.B*power;
[t,x] = ode45(func,0:1:50,zeros(size(M.A,1),1));
y = M.C*x';
y = y+T0;

Plot the result:

figure, plot(t,y), grid

Evaluate the steady state temperature value:

G = M.D-M.C*(inv(M.A))*M.B;
y = full( G*power );
y = y + T0

272 |

CHAPTER 6: COMMAND REFERENCE

mphtable
Get table data.

Purpose

mphtable

Syntax

info = mphtable(model,tabletag)

Description

info = mphtable(model,tabletag) returns the structure info containing the

data with the tabletag tag and its headers.

The returned value info is a structure with the following content
TABLE 6-30: FIELDS IN THE INFO STRUCT

Example

FIELD

CONTENT

Headers

Headers of the table

Tag

Tag of the table

Data

Data of the extracted table

Filename

Filename when table exported to file

Load model_tutorial_llmatlab.mph, add a stationary study and compute the

solution for different power values:
model = mphload('model_tutorial_llmatlab');
std = model.study.create('std');
stat = std.feature.create('stat','Stationary')
stat.setIndex('pname','power',0);
stat.setIndex('plistarr','30 60 90',0);
std.run;

Evaluate the maximum temperature in the model and set the results in a table:
max = model.result.numerical.create('max','MaxVolume');
max.selection.all;
tbl = model.result.table.create('tbl','Table');
tbl.comments('Volume Maximum (T)');
max.set('table','tbl');
max.setResult;

Extract the table data:

str = mphtable(model,'tbl');
tbl_data = str.data
See Also

mpheval, mphevalpoint, mphglobal, mphint2, mphinterp, mphmax, mphmean,

mphmin

273

mphversion
Return the version number of COMSOL Multiphysics.

Purpose

mphversion

Syntax

v = mphversion
[v,vm] = mphversion(model)

Description

v = mphversion returns the COMSOL Multiphysics version number that

MATLAB is connected to as a string.
[v,vm] = mphversion(model) returns the COMSOL Multiphysics version
number that MATLAB is connected to as a string in the variable v and the version
number of the model in the variable vm.

Example

Load model_tutorial_llmatlab.mph:
model = mphload('model_tutorial_llmatlab');

Get the version numbers:

[version, model_version] = mphversion(model)

274 |

CHAPTER 6: COMMAND REFERENCE

mphviewselection
Display a geometric entity selection in a MATLAB figure.

Purpose

mphviewselection

Syntax

mphviewselection(model,geomtag,number,entity,...)
mphviewselection(model,seltag,...)

Description

mphviewselection(model,geomtag,number,entity,...) displays the

geometric entity number of type entity in MATLAB figure including the
representation of the geometry geomtag.
mphviewselection(model,seltag,...) displays the geometric entity selection
seltag in a MATLAB figure including the representation of the geometry.

The function mphviewselection accepts the following property/value pairs:

TABLE 6-31: PROPERTY VALUE/PAIRS FOR THE MPHVIEWSELECTION FUNCTION
PROPERTY

VALUE

DEFAULT

DESCRIPTION

Edgecolor

Char | RGB array

Color for edges

Edgecolorselected

RGB array

[1,0,0]

Color for selected

edges

Edgelabels

on | off

off

Show edge labels

Edgelabelscolor

Char | RGB array

Color for edge labels

Edgemode

on | off

on

Show edges

Entity

Domain |
boundary | edge
| point

Facealpha

Double

Set transparency value

Facecolor

RGB array

[0.6,0.6,0.6]

Color for face

Facecolorselected

RGB array

[1,0,0]

Color for selected

face

Facelabels

on | off

off

Show face labels

Facelabelscolor

Char | RGB array

Color for face labels

Facemode

on | off

on

Show faces

Geommode

on | off

Marker

Set the selected entity

type

on

Show entire geometry

Vertex marker

Markercolorselected

Char | RGB array

Color for selected

vertex marker

Markersize

Int

12

Font size of marker

Parent

Double

Parent axis

275

mphviewselection

TABLE 6-31: PROPERTY VALUE/PAIRS FOR THE MPHVIEWSELECTION FUNCTION

PROPERTY

VALUE

DEFAULT

DESCRIPTION

Renderer

Opengl |
zbuffer

opengl

Set the rendering

method

Selection

String | Positive
integer array

Selectoralpha

Double

0.25

Set selector
transparency value

Selectorcolor

RGB array

[0,0,1]

Color for selected

marker

Showselector

on | off

on

Show Selector

Vertexlabels

on | off

off

Show vertex labels

Vertexlabelscolor

Char | RGB array

Color for vertex

labels

Vertexmode

on | off

off

Show vertices

Example

Set selection name or

entity number

Plot boundary 6 using yellow color:

model = mphload('model_tutorial_llmatlab');
mphviewselection(model,'geom1',6,'boundary',...
'facecolorselected',[1 1 0],'facealpha',0.5)

Plot edges 1 to 8 using green color:

mphviewselection(model,'geom1',1:8,'edge',...
'edgecolorselected',[0 1 0])

Add an explicit selection for boundaries 7 to 12 and plot the selection in a figure:
model.selection.create('sel1','Explicit').geom(2).set(7:12);
mphviewselection(model,'sel1');

Add a selection to get the vertex indices with the box delimited with the coordinates
[-1e-3 11e-3;-1e-3 11e-3;9e-3 11e-3] and plot both the selected entities and the
selector:
box = model.selection.create('box1', 'Box');
box.set('entitydim', '0');
box.set('xmin', '-1e-3').set('xmax', '11e-3');
box.set('ymin', '-1e-3').set('ymax', '11e-3');
box.set('zmin', '10e-3').set('zmax', '11e-3');
mphviewselection(model,'box1','facemode','off');
See also

276 |

CHAPTER 6: COMMAND REFERENCE

mphgeom, mphselectbox, mphselectcoords

mphxmeshinfo
Extract information about the extended mesh.

Purpose

mphxmeshinfo

Syntax

info = mphxmeshinfo(model)

Description

The Xmesh information provide information about the numbering of elements,

nodes, and degrees of freedom (DOFs) in the extended mesh and in the matrices
returned by mphmatrix and mphgetu
Information is only available on StudyStep and Variables features.
The function mphxmeshinfo accepts the following property/value pairs:
TABLE 6-32: PROPERTY VALUE/PAIRS FOR THE MPHVIEWSELECTION FUNCTION
PROPERTY

VALUE

DEFAULT

DESCRIPTION

Solname

String

Active
solution
object

Solution object tag

Studysteptag

String

Meshcase

Positive
integer |
String

Study step node tag

First mesh

Mesh case tag

The function xmeshinfo returns a structure with the fields shown in the table below
TABLE 6-33: FIELD IN THE RETURNED STRUCTURE FROM MPHXMESHINFO

Example

FIELD

DESCRIPTION

Solname

Tag of the solution object

Ndofs

Number of DOFs

Fieldnames

Names of the field variables

Fieldndofs

Number of DOFs per field name

Meshtypes

Types of mesh element

Dofs

Structure with information about the degrees of

freedom

Nodes

Struct with information about the nodes

Elements

Struct with information about each element type

Extract xmesh information:

model = mphload('model_tutorial_llmatlab.mph');
std = model.study.create('std');
std.feature.create('stat', 'Stationary');
std.run;
info = mphxmeshinfo(model)

277

mphxmeshinfo
Get the number of degrees of freedom and the nodes coordinates:
dofs = info.ndofs
coords = info.dofs.coords;

Get the DOFs indices connected to the tetrahedron:

idx = info.elements.tet.dofs

Retrieve the xmesh information with several physics

model = mphload('model_tutorial_llmatlab.mph');
ec = model.physics.create('ec','ConductiveMedia','geom1');
ec.feature.create('gnd1','Ground',2).selection.set(3);
pot = ec.feature.create('pot','ElectricPotential',2);
pot.selection.set(7);
pot.set('V0',1,'50[mV]');
hs = model.physics('ht').feature('hs1');
hs.set('heatSourceType',1,'generalSource');
hs.set('Q_src',1,'root.comp1.ec.Qh');
std = model.study.create('std');
std.feature.create('stat', 'Stationary');
std.run;
info = mphxmeshinfo(model)

Get the index of the nodes for element with the index 100:
idx_nodes = info.elements.tet.nodes(:,100)

Get the index of the dofs for element with the index 100:
idx_dofs = info.elements.tet.dofs(:,100)

Get the index of the variables names corresponding to the dofs with the index
idx_dofs:
idx_names = info.dofs.nameinds(idx_dofs);

Find the dofnames index corresponding to the variable V:

idx_dofnames = find(strcmp(info.dofs.dofnames,'comp1.V'))-1;

Get the list of dofs that correspond to the variable V:

idx = find(idx_names==idx_dofnames)

Get the coordinates of the dofs corresponding to the dependent variable V that
belong to element 100:
info.dofs.coords(:,idx_dofs(idx))
See also:

278 |

mphgetu, mphmatrix, mphsolinfo

CHAPTER 6: COMMAND REFERENCE

I n d e x
A

adding

model objects 26

animations 112

client-server mode 16

ball selections 92

cluster computing 104

box selections 94

color display, selections 98

geometry operations 31

color tables 108

global equations 86

combining meshes 66

interpolation functions 88

compose operation 35

job sequences 104

composite object, creating 34

MATLAB feature node 191

COMSOL API 24

mesh sequences 52

COMSOL exceptions 177

parametric sweeps 103

COMSOL Multiphysics binary files 73

physics interfaces 45, 82

COMSOL Multiphysics text files 73

plot groups 106

COMSOL Physics Builder 89

study nodes 100

COMSOL server 16

adjacent selections 95

connect to server 29

advancing front method 58

connecting MATLAB 18

animation export 112

constructor name 81

animation player 114

converting

ASCII format 112

curve segments 38

average of expressions 135

image data 49

ball selections 92, 97

image file to data 48

batch jobs 104

mesh elements 72
copying

batch mode 145

boundary meshes 70

boundary layer meshes 67

mphnavigator properties 173

boundary meshes 70

creating

boundary modeling 37
box selections 94, 97

1D geometries 33

building

2D geometries 34, 37

geometry sequences 32

3D geometries 38

mesh sequences 53

composite objects 34

meshes 62

geometry from image data 48

materials 85

CAD formats 41

mesh information 77

calling MATLAB functions 21, 117

model objects 25

clearing

curve interpolation, example 46

functions 192
D

data export 113

INDEX|

279

data sets syntax 110

expression average 135

data, extracting 119

extended mesh 167

defining

extracting

materials 85

data 119, 123

MATLAB functions 188

eliminated matrices 149

selections 91

matrices 156

settings 88

mesh information 77

Delaunay method 58

plot data 108

derivative recovery 126

solution vectors 165

difference operation 35

system matrices 147

directory path, MATLAB function 190

disabling model history 181

extruding meshes 6465

F

disconnecting MATLAB 20

free meshing 66

displaying

free quad mesh, example 59

geometries 32

free triangle mesh, example 58

meshes 53

function derivatives 192

plot groups 107

function inputs/outputs 191

selections 97

functions

documentation 11

interpolation 88

dofs, xmesh 168

MATLAB 117

DXF files 41
E

element, xmesh 168

floating network license (FNL) 19

MATLAB, adding 186

G

emailing COMSOL 13

GDS format 41
geometry

enabling model history 181

creating 46

entity, geometry 33

displaying 32

equations, modifying 85

exporting 40

errors 177

parameterized 43

evaluating

parametrization, example 143

data 111

retrieve information 42

expressions 120

sequence 31

global expressions 131

global equations 86

global matrix 133

global expressions 131

integrals 129

global matrix 133

explicit selections 91
exporting

history, model 27

data 113
geometries 4041
plugins 90

280 | I N D E X

Hankel function 189

image data conversion, example 49

image data, create geometry 48

importing

quality 74

meshes 73

refining 69

imread (MATLAB function) 48

resolution 55

inner solution 162

sequence 52

integrals, evaluating 129

importing 73

geometries 41

statistics 75

Internet resources 10

methods 24

interpolation curve 46

methods, mphnavigator 174

interpolation functions 88

Microsoft Windows 17

Java 24
Java heap size 179
job sequences 104

minimum of expressions 137

model examples 10
model expressions 175
model features 180

knowledge base, COMSOL 13

linear matrix 150

Model Library 12

linearization points 148, 157

model object

model history 27, 181

Linux 17

calling 117

list model object 26

create custom GUI 182

load model 27

information 174

loops 142, 181

methods 25

Mac OS X 17
mass matrix 156
materials 8485
MATLAB desktop 16
MATLAB feature node 191
MATLAB functions 117, 186
MATLAB functions, plot 188
matrices, state-space 155
maximum of expression 133
measuring, mesh quality 74
memory requirements 181
mesh
boundary layers 67
converting 72
copying 70
data 76
displaying 53
element size, controlling 54

navigating 170
Model Tree 172
models, running in loops 142
ModelUtil method 25
modifying equations 85
mpheval 120123
mphevalglobalmatrix 133
mphevalpoint 126128
MPH-files 12
mphgetexpressions 176
mphgetproperties 176
mphgetselection 176
mphgetu 165166
mphglobal 131133
mphinputmatrix 150151
mphint2 129131
mphinterp 123126
mphmatrix 147149

INDEX|

281

mphmax 133135

results evaluation 111

mphmean 135137

revolved prism mesh, example 64

mphmin 137139

revolving face meshes 64

mphmodel 174

run solver sequences 102

mphnavigator 170174

running, models in loops 142

mphparticle 139141
mphsearch 175
mphshowerrors 177
mphsolinfo 160161
mphsolutioninfo 162164
mphstate 155158
mphtable 119
mphxmeshinfo 154, 167168
myscript 145
N

save model object 28

selecting, linearization points 148
selections
defining 91
displaying 97
sequences of operations 24
sequences, solvers 102
set method 116
set operations 35

NASTRAN 73

set the feature property 32

node points 120

setindex method 117

nodes, xmesh 168

setting

numerical node syntax 111

O

ODE problem, example 87

outer solution 162

linear matrix system 150

linearization points 157
simplex elements 69
solid modeling 38

parameterized geometries 43
parametric jobs 104
parametric sweep 103
particle trajectories 139
physics interfaces 8182
plot data, extracting 108
plot groups 106107
plot while solving 104
plotting data, example 109
port number 16
preferences 20
prism mesh 65
progress bar 26

quadrilateral mesh, example 60

refining meshes 69
remove model object 26
resolution, mesh 55

282 | I N D E X

solution information 160, 162

solution object 160
solution vector 165
solutions, specifying 165
solver configurations syntax 101
solving, ODE problems 87
squeezed singleton 128
state-space export 155
statistics, mesh 75
STL format 41
structured meshes 60
study syntax 100
sweeping meshes 64
swept meshing 66
syntax
data sets 110
materials 84

numerical node 111

physics interfaces 81
plot groups 106
solver configurations 101
studies 100
system matrices 147
T

table data 119

technical support, COMSOL 13
tolerance radius 93
transparency, selections 98
triangular mesh, example 55

updates, disable 180

user community, COMSOL 13
user-defined physics interface 89

VRML format 41

W warnings 177

weak form equation, example 86

web sites, COMSOL 13
X

xmesh 167
xterm 145146

INDEX|

283

284 | I N D E X