Best Practice for Working with Model M-Files
Lars Gregersen May 14, 2014
When developing models in COMSOL Multiphysics® software, it is common to come across tasks that have to be carried out repeatedly. This three-part blog series will show you how repetitive tasks can be efficiently achieved using model M-files and LiveLink™ for MATLAB®.
Introducing Variations into Models
You can introduce many variations into your models through the COMSOL Multiphysics user interface (UI). Functionality, such as parametric sweeps and optimization, allow you to vary a set of parameters in tailor-made edit fields for this purpose.
Yet, some types of variations are not catered to by the UI. In these cases, LiveLink™ for MATLAB® comes in handy as it can access all the model settings, using the COMSOL® API for use with Java® (COMSOL API).
With LiveLink™ for MATLAB®, it is possible to:
- Start simulations automatically from a MATLAB® program
- Introduce changes to model settings through the use of scripting
- Create models from scratch
- Creating the geometry, meshing, defining physics, calling a solver, and postprocessing the results
- Read CAD files and files containing meshes
- Connect to other data sources and read data from files, databases, etc.
- Create a simplified UI for novices to run models
Many of these features are important if you wish to avoid repeating your work in the COMSOL Multiphysics UI.
Building a Model from Scratch Using LiveLink™ for MATLAB®
If you are new to LiveLink™ for MATLAB®, then the Introduction to LiveLink™ for MATLAB® manual provides sufficient information to get you started. In particular, the LiveLink™ for MATLAB® User’s Guide provides further resources about the commands within the COMSOL Multiphysics API and the equivalent MATLAB® functions they access. You can actually create your first model M-file, which controls a COMSOL Multiphysics model, without having to read this documentation. This is because such scripts can be auto-generated from the COMSOL Multiphysics UI.
Let’s look at a simple heat transfer example that only requires the COMSOL Multiphysics base package to build and solve. The geometry can be seen in the following figure, where a heat flux is introduced at the bottom boundaries and dissipates into the surrounding air at the top boundaries.
The geometry consists of a few rectangles that are either combined with or subtracted from each other. The M-file code for making this geometry can be seen below:
Here, the code is commanding COMSOL Multiphysics to create rectangle nodes in the model tree, as well as the node that takes the difference between rectangles. You see that the size and position (pos) of the entities are defined. These definitions can be used to define the geometry as you’d like it to be. It is evident that even small geometries may lead to a lot of defining code. The next section shows how to create lines automatically.
Automatic Generation of Model M-files
All functionality within COMSOL Multiphysics can be represented by a line of code, and a full model would correspond to many lines of code. Instead of creating a model from scratch using a script, you can create it in the COMSOL software UI and then save it as an M-file. This is done by choosing File > Save as and then selecting “Model File for MATLAB (*.m)”.
Such an M-file contains all the steps that have been followed when building the model. By running the file using LiveLink™ for MATLAB®, you will notice that all the commands that were performed are recorded. If the model was solved several times, there will be several calls to the solvers, which you typically don’t want. If you were to run the model from the MATLAB® command line, it will solve the model several times. In order to obtain an M-file that is compact, you can choose File > Compact History before saving the file.
Now that we have the entire model as an M-file, we are free to investigate — or change — any of the settings in the model. We can add new features to the model, as well.
Have a look at your M-file and see if you can identify the various sections of the model and how things are set up. Some things will be easy to understand in a model, such as how parameters and the geometry are defined. Other things, such as solver or plots settings, can be more obscure. However, if you have MATLAB® coding experience, you should easily be able to see where things are defined.
In the following example snippet:
you can see how the mesh settings are defined. When an M-file contains the definition of the geometry, physics, mesh, solvers, etc., a call is made to a “run()” method. This takes all the commands in the M-file and executes them in COMSOL Multiphysics. Calls to “run()” may take a long time if your model is big, so if you wish to follow the solution progress, you can switch on the Progress window by using this code (before calling run):
Working Even Faster Without Model M-Files
If you use MATLAB® to change a model using the COMSOL software API and lose track of changes, it is nice to know that you can always save the model as an MPH-file, load it into the COMSOL Multiphysics UI, and inspect it there. Furthermore, you can load MPH-files into MATLAB® and manipulate them from there, as well.
The following example loads an MPH-file and performs a “for” loop on the parts of the model that has changed (its geometry) before solving it.
One of the biggest reasons for working with M-files is to be able to manipulate geometries. In order to do this, you need to understand Selections:
The above code sets up some of the heat transfer physics, including two boundary conditions for a “Heat Flux Boundary” on a series of boundaries, identified by numbers. When a geometry is changed in a way that introduces more domains, boundaries, or vertices, these numbers will change too. You will need a way to either track these numbers, or avoid using them.
These will be the topics of the next two blog entries in this series. Stay tuned.
MATLAB is a registered trademark of The MathWorks, Inc.