Problem Description
This solution describes how to launch a parametric sweep, a batch sweep, or a cluster sweep simulation in COMSOL Multiphysics® from the command line.
Solution
Short Summary
Model methods are presented as a concept to modify Parametric Sweep, Batch Sweep, and Cluster Sweep nodes by, for example reading parameter cases from files. The -mode desktop option can be used to run Batch Sweep and Cluster Sweep nodes from the command line and to obtain synchronized solutions and synchronized accumulated probe table in the output file.
Framework
COMSOL Multiphysics® offers various possibilities to control and run parameter sweeps in sequential and in distributed mode:
Parametric Sweep
The Parametric Sweep feature in COMSOL Multiphysics® is used to run a parametric study with several parameter cases in a single instance of COMSOL Multiphysics®. The parameter cases are typically handled one after the other and all compute resources (processes and cores) assigned to the single COMSOL Multiphysics® instance are used. The Parametric Sweep node is controlling the parameter ranges of the corresponding parametric study. You can run the study either from the GUI or from the command line, for example by specifying the flag -std as an option for the COMSOL batch call. The solutions in the study are either available as parametric values in the solution sequence (if the Parametric Solver is used), or under a Parametric Solutions node (if an outer sweep with an additional Parametric Sweep node under Job Configurations is used; see the figure below).
See Performing a Parametric Sweep Study in COMSOL Multiphysics® for a video instruction of how to set up a Parametric Sweep.
Distributed Parametric Sweep
If the Parametric Sweep study is run in a distributed memory parallel environment
- as a Parametric Sweep node combined with a Cluster Computing node in a study,
- or in a distributed GUI instance, for example launched by
comsol -nn 4 -nnhost 4(no Cluster Computing node is required in this case), - or in a cluster job launched by a submission script for the scheduler,
you can use the Distribute parametric sweep option in the Study Extension section of the Parametric Sweep (or the Distribute parametric solver option of a Stationary study step). With this option enabled, the parameter cases of the Parametric Sweep are distributed across the running compute processes. When running, for example four parameter cases on two nodes, each node will handle two parameter cases and the nodes are accomplishing their work simultaneously. The parametric solutions for all parameters are available in the output file (from a batch run) or in the GUI (for an interactive distributed COMSOL instance).
Batch Sweep
The Batch Sweep — in contrast to the Parametric Sweep — is using multiple COMSOL batch instances to process the parameter cases. The instances are launched as external batch jobs from a Batch Sweep study run in the GUI. These jobs are running independently of each other and in case of a failure in one job, the other jobs and their results are not affected. The results are stored in the corresponding output files. In addition, there are options to Synchronize solutions and to Synchronize accumulated probe table in the Batch Settings section of the Batch Sweep node. With the Synchronize solutions option, the parametric solutions of all jobs will be available in the model in the GUI for postprocessing.
Batch Sweeps automatically adjust the number of cores used to an optimal value, but you can also set the resources for the jobs manually. If an external job should use only a subset of the available cores, you can set the Number of cores per job (can be set on the Batch node under Job Configurations; see the figure below) and the Number of simultaneous jobs (can be set on the Batch Sweep node). The product of these two values should not exceed the number of available cores.
Additional information on Batch Sweeps can be found in the blog The Power of the Batch Sweep.
Cluster Sweep
A Cluster Sweep provides the same functionality as a Batch Sweep plus interfaces for cluster computing settings and remote and cloud access. You can configure the external jobs for distributed execution in a cluster environment. The options Synchronize solutions and Synchronize accumulated probe table are available in the Batch Settings section of the Cluster Sweep node as well. The usage and the configuration of a Cluster Sweep node is described in the blog post How to use the Cluster Sweep Node in COMSOL Multiphysics®.
NOTE: A Floating Network License (FNL) is required to run COMSOL Multiphysics® in distributed memory parallel mode. This applies for example to studies with a Cluster Computing node (for a distributed Parametric Sweep), studies with a Cluster Sweep node, or to distributed GUI instances with a distributed Parametric Sweep (see Running COMSOL® in parallel on clusters for a description of the modes of cluster execution).
Running a parametric sweep from the command line
A study containing a Parametric Sweep node can be run from the command line, for example by invoking
COMSOL batch -inputfile mymodel.mph -outputfile out.mph -study std1
and in case of a distributed Parametic Sweep, for example by launching
COMSOL batch -nn 4 -nnhost 4 -inputfile mymodel.mph -outputfile out.mph -study std1
In both cases, the Parametric Sweep is running as is; that is, it runs with the parameter values stored in the Parametric Sweep node in the model.
If you want to prescribe the set of parameters for a sweep from the command line, you can instead disable the Parametric Sweep node in the model file and use the flags -pname and -plist to set the parameters by command-line input or you can read the parameters from a file using the -paramfile flag. If you use these command-line approaches, a different output file is generated for each parameter case and the solutions are not synchronized to a single file.
An example application from the application library with a Parametric Sweep is the Tuning Fork. This model determines the fundamental resonant frequency of a tuning fork where the prong length L is varied in the parametric sweep. You can call this model (having the Parametric Sweep disabled in the GUI) from the command line for a given parameter range by invoking, for example
comsol batch -inputfile tuning_fork.mph -outputfile tuning_fork_out.mph \
-pname L -plist 8[cm],10[cm],12[cm]
in order to sweep over the parameters L=8[cm], 10[cm], and 12[cm] (resulting in an output file for each parameter). For a space-separated parameter file paramfile.dat, which contains the parameter names in the first row and the corresponding parameter value tuples in the following rows, for example
L
0.08
0.10
the call for a parameter-file controlled parameter sweep may look like
comsol batch -inputfile tuning_fork.mph -outputfile tuning_fork_out.mph \
-paramfile paramfile.dat
Controlling a Parametric Sweep by a model method
Another option for controlling a Parametric Sweep from the command line is to use a model method for reading the desired parameters from an input file. In the following example, the model method reads the input file and extracts the parameter names, the parameter values, and the parameter units. The extracted values are used to set the corresponding properties on the Parametric Sweep node. Finally, the Parametric Sweep is done by running the Parametric Sweep subnode under Job Configurations (assuming this node has been created before, for example by running the study in the GUI). The following example code can be used to define a new model method in the Application Builder:
// Load the csv parameter file with format
// pname0, pname1, ...
// punit0, punit1, ...
// pval00, pval10, ...
// pval01, pval11, ...
// ..., ..., ...
String thisStudy = "std1";
String thisFeature = "param"; // Parametric Sweep (*)
String thisParam = "p1";
String fileName = "C:\\models\\pfile.csv";
String[][] pArr = readCSVFile(fileName);
int rows = pArr.length;
int cols = pArr[0].length;
String pNames = "";
String pUnits = "";
String[] pValues = new String[cols];
// Read names from line 0
pNames = pArr[0][0];
for (int col = 1; col < cols; col++)
pNames = pNames+","+pArr[0][col];
// Read units from line 1
pUnits = pArr[1][0];
for (int col = 1; col < cols; col++)
pUnits = pUnits+","+pArr[1][col];
// Read values from lines 2,3,...
for (int col = 0; col < cols; col++)
pValues[col] = pArr[2][col];
for (int row = 3; row < rows; row++)
for (int col = 0; col < cols; col++)
pValues[col] = pValues[col]+","+pArr[row][col];
// Set parameters for thisStudy / thisFeature
with(model.study(thisStudy).feature(thisFeature));
set("plistarr", new int[]{});
set("plistarr", pValues);
set("pname", new String[]{});
set("pname", pNames);
set("punit", new String[]{});
set("punit", pUnits);
endwith();
// Run param sweep
model.batch(thisParam).run(); // (**)
See How to Use Model Methods to Accelerate Your COMSOL Workflow for an introduction to model methods. In the Model Builder you can add a method call to the previously defined model method under Global Definitions by selecting Add Method Call on the Developer tab. You can test the model method by right-clicking the Modelmethod1 node and selecting Run.
The parameter file pfile.csv is a comma-separated text file where the first line contains the parameter names (L), the second line contains the units for the parameter columns (cm), and the third to n-th lines contain the parameter values for this parameter's column (8, 10).
L
cm
8
10
With this configuration the Parametric Sweep can be run from the command line by calling the model method
comsol batch -inputfile tuning_fork.mph -outputfile tuning_fork_out.mph \
-methodcall methodcall1
with the additional flag -methodcall methodcall1. The parameters in the sweep are those defined in the parameter file loaded by the model method. If you want to run several sweeps for different parameter files, the model method can be modified to load several parameter files and to run several sweeps in a row, or you can define several model methods that are called in consecutive runs from the command line. A nested loop of parameters is automatically set up and used when the parameter file contains multiple columns (the parameters need to be defined in the study).
If the Parametric Sweep uses the Parametric Solver (see the figure below), the model method needs to run the corresponding solver sequence, that is, the line (**) needs to be replaced by
...
model.sol("sol1").runAll(); // Parametric solver (**)
NOTE: The Application Builder is supported in the Windows® operating system.
Running a Batch Sweep or a Cluster Sweep from the command line
If you have a study with a Batch Sweep or a Cluster Sweep and you run the study in batch mode from the command line, the Batch Sweep and the Cluster Sweep nodes are ignored by default. If you want to run these nodes as well (that is, if you want to allow the batch process to launch external processes), you have to add the flag -mode desktop to the batch call on Windows
comsolbatch.exe -mode desktop -inputfile tuning_fork.mph -outputfile tuning_fork_out.mph
and
comsol batch -mode desktop -inputfile tuning_fork.mph -outputfile tuning_fork_out.mph
on Linux or MacOS (in version 5.3a you have to use -batch off on Linux / MacOS instead of -mode desktop).
In both cases, the Batch Sweep or the Cluster Sweep are run as is, that is, with the parameters defined inside the model file. If the options Synchronize solutions or Synchronize accumulated probe table are checked, the synchronizations are performed in the same way as in a run from the GUI. The big plus of this command-line approach is that it allows you to obtain an outputfile with synchronized solutions from all external jobs for further postprocessing.
If you want to hand over the parameters for the Batch Sweep or the Cluster Sweep by a parameter file that is read by a variant of the presented model method, you need to modify the line (*) in the above example and define
...
String thisFeature = "batsw"; // Batch Sweep (*)
...
for a Batch Sweep and
...
String thisFeature = "clusw"; // Cluster Sweep (*)
...
for a Cluster Sweep. In addition, the line (**) needs to be replaced by the lines
...
String thisBatch = "b1"; // for Batch / Cluster Sweep (**)
model.batch(thisBatch).feature("daDef").feature().remove("pr1");
model.batch(thisBatch).feature("daDef").feature().remove("pr2");
model.batch(thisParam).run();
model.batch(thisBatch).feature("daDef").run();
Here, it is assumed that the corresponding study has already been run in the GUI, and that the Parametric Sweep node p1 and the Batch node b1 under Job Configurations have already been generated. In addition, it is assumed that there are two old external process nodes to be removed before the new ones will be generated.
For launching the Batch Sweep or the Cluster Sweep controlled by the model method you have to invoke
comsolbatch.exe -mode desktop -inputfile tuning_fork.mph -outputfile tuning_fork_out.mph \
-methodcall methodcall1
on Windows or
comsol batch -mode desktop -inputfile tuning_fork.mph -outputfile tuning_fork_out.mph \
-methodcall methodcall1
on Linux or MacOS (use -batch off in version 5.3a instead of -mode desktop).
COMSOL makes every reasonable effort to verify the information you view on this page. Resources and documents are provided for your information only, and COMSOL makes no explicit or implied claims to their validity. COMSOL does not assume any legal liability for the accuracy of the data disclosed. Any trademarks referenced in this document are the property of their respective owners. Consult your product manuals for complete trademark details.