COMSOL 6.3 - COMSOL Commands on Linux

Use the comsol command to start COMSOL products with detailed startup options.

The general syntax of the COMSOL command is

comsol [<target>] [<options>] [<target arguments>]

where square brackets indicate optional arguments. The comsol command can be combined with optional targets to achieve various results. The table below lists the command and targets:

Table 22-16: COMSOL Commands and Targets.
command and Target	Description	Availability
comsol	Run standalone COMSOL Multiphysics
comsol batch	Run a COMSOL MPH-file or class file
comsol compile	Compile a model file for Java or compile an application into an executable application (the latter option requires COMSOL Compiler)
comsol doc	Launch the COMSOL Documentation window
comsol mphclient	Run COMSOL Multiphysics client
comsol mphserver	Start COMSOL Multiphysics server
comsol mphserver matlab	Start MATLAB® and connect to a COMSOL Multiphysics server	Requires LiveLink™ for MATLAB® license
comsol hydra	Run COMSOL Hydra commands	Requires CLUSTERNODE license.
comsol trust	Trust methods in add-ins

The comsol command is located in the bin folder in the COMSOL installation directory.

INI Files

There is a number of .ini files in the subdirectories glnxa64 and glnxarm64 in the bin directory. It is sometimes recommended that you edit these files. For example, you can add options to any of the above commands by modifying the corresponding ini file. To change the option opt to value val, add the line

-Dopt=val

to the file comsol.ini. Change the file comsolbatch.ini for comsol batch, and similarly for the other COMSOL targets.

Options

You can enter various options after the comsol command and target. Table 22-17 lists the options (See [<options>] in the command syntax) available for all comsol commands. Always issue these options between the command and the target (if any).

Table 22-17: COMSOL options on Linux (curly braces indicate default values).
COMSOL option	Description
<target> -h	Print target-specific help.
-3drend ogl \| sw	3D renderer: OpenGL or software rendering.
-alloc {native} \| scalable	Memory allocator: Select from using the Linux® native memory allocator or the scalable memory allocator from the Intel® Threading Building Blocks library.2
-applicationsroot <path>	Specify custom path to the COMSOL Application Libraries root directory.1
-autosave {on} \| off	Control saving of recovery files.
-blas {auto} \| mkl \| aocl \| armpl \| openblas \| blas \| path	BLAS library to use.3 mkl and aocl are supported for Intel and AMD processors. armpl and openblas are supported for ARM processors.
-blaspath <path>	BLAS library path.3
-c <path>	License file path.
-ckl	Use class-kit license.
-clusterpartmethod {off}\|mo\|nd\|wnd	Cluster partitioning method. Choose from mesh ordering (mo), nested dissection (nd), or weighted nested dissection (wnd).
-clusterstorage all \| single \| shared	Cluster storage format. The single format does I/O only from the root node, while the shared format does I/O using distributed I/O operations. The shared format requires that all nodes have access to the same storage area and the same temporary storage area.
-comsolinifile <path>	Specify custom path to .ini-file used when starting COMSOL.
-configuration <path>	Path to directory for storing the state for the GUI between sessions and for performing different caching tasks. The configuration directory is by default a subdirectory to the preference directory. However, the default location of the configuration directory is not affected if you use the -prefsdir option. When running in batch or cluster mode, add @process.id to get a unique identifier to the path (for example, -configuration /tmp/comsol_@process.id).
-data	Path to a workspace directory for storing internal workspace information. The workspace directory is by default a subdirectory to the preference directory. However, the default location of the workspace directory is not affected by the -prefsdir option. The workspace directory is cleared when COMSOL is launched. When running in batch or cluster mode, add @process.id to get a unique identifier to the path (for example, -data /tmp/comsol_@process.id).
-docroot <path>	Specify custom path to the COMSOL documentation root directory. 1
-forcegcc	Force load of GCC libraries.
-h	Print general help.
-keeplicenses on \| {off}	Keep checked-out licenses when creating or opening an application.
-memoptassem {off} \| matrix \| vector \| on	Control of scalability assembling mode.
-mpmode throughput \| turnaround \| owner	Multiprocessor mode.2
-np <no. of cores>	Number of cores.2
-numafirst <numa number>	Set first NUMA node (socket) to bind process to.2
-numasets <no. of sets>	Number of NUMA sets (sockets).2
-prefsdir <path>	Preference directory.
-recoverydir <path>	Path to recovery directory. The recovery directory is by default a subdirectory to the preference directory.
-tmpdir <path>	Temporary file directory. Whitespace is not supported in the file directory path,
-v, -version	Print COMSOL version.
Reference
1 See Documentation and Application Libraries Root Directories. 2 See Shared-Memory Options. 3 See BLAS Options.

For the -tmpdir option, the COMSOL Multiphysics software uses the specified directory to store temporary files. Use the -prefsdir option to specify the directory where COMSOL Multiphysics stores the preference file.

Documentation and Application Libraries Root Directories

In a default COMSOL Multiphysics installation, the documentation files are located in the directory doc under the installation root directory. You can use the -docroot option if you want to move the documentation directory to a different location. Similarly, use the -applicationsroot option if you want to move the Application Libraries root directory applications from its default location under the COMSOL Multiphysics installation root. Relocating the documentation and Application Libraries root directories can be useful for administering Application Library Update; see The Application Library Update Window.


	Setting the paths to the documentation and Application Libraries root directories using these options does not in itself move the directories and their contents.

Shared-Memory Options

Use the option -np to control the number of cores used. The default is to use all available cores (processing units).

Use the option -numasets to control the number of nonuniform memory access (NUMA) node sets that the COMSOL Multiphysics software should take into account. This is usually the number of processor sockets that the hardware is using. If you only set the -np option, the number of sockets is determined automatically so that sufficient number of sockets are used by default.

Depending on how loaded the machine is, you can control how COMSOL Multiphysics uses the available processors with the -mpmode option. The following options are available:

Table 22-18: COMSOL Multiprocessor Mode Options.
MPMODE Option	Description
owner	Provides the highest performance in most cases.
throughput	Is expected to give the best performance when several different processes are running actively at the same time as COMSOL Multiphysics.
turnaround	Typically provides the best performance when no other processes than COMSOL Multiphysics are active.

Use the option -alloc to specify memory allocator type. The default is to use the native memory allocator. The scalable memory allocator can increase performance significantly for computers with many cores but uses more memory.


	You can also specify the number of cores and sockets and the use of the scalable allocators as preferences on the Computing>Multicore page in the Preferences window. To specify those numbers manually, select the Number of cores and Number of sockets checkboxes to enter a number in the associated text fields. By default, all cores are used and the number of sockets are set automatically. If you lower the number of cores, it is good practice to also lower the number of sockets. The preference option for the scalable allocator is called Optimized for multicore. If you want to choose another memory allocator than the default setting, select the Memory allocator checkbox and the choose Native or Optimized for multicore. To control the scalability assembling mode, which can be useful even when running on a single node, select the Memory scalability optimization for assembling checkbox. You can then select Off (the default, for no scalability mode), Matrix for activating scalability mode only for matrix assembling, Vector for activating scalability mode only for vector assembling, or All for activating scalability mode for all cases. You can also control these options with a command-line argument -memoptassem.

Sometimes you might want to experiment to find the options that work best for your configuration.

BLAS Options

BLAS is a set of functions for basic linear algebra operations. A large portion of the computational engine in the COMSOL software relies on BLAS. The COMSOL software provides for the following BLAS-related options:

Table 22-19: COMSOL BLAS Options.
BLAS Option	Description
auto	The default option is to use the Intel MKL library for Intel and AMD processors. For ARM processors, the default library is Arm Performance Libraries.
mkl	Use the Intel MKL library (included with installation for Intel and AMD processors).
aocl	Use the AMD Optimizing CPU Libraries (included with installation for Intel and AMD processors). (The obsolete BLAS option blis uses the AMD Optimizing CPU Libraries.)
armpl	Use the Arm Performance Libraries (included with installation for ARM processors).
openblas	Use the OpenBLAS library.
blas	Use the standard BLAS library (included with installation).
path	Use a BLAS library specified using the option -blaspath or the environment variable COMSOL_BLAS_PATH.

If you want to use a different BLAS library than the ones provided by COMSOL, make sure that COMSOL Multiphysics can find the library. The simplest way for COMSOL Multiphysics to find a library is to put it in /lib/win64 or somewhere in the standard search path. Also provide the path to any sublibraries needed by the library. Set the search path to point to the directory where the library is installed. To do so, use the environment variable PATH. Your library must support both the standard FORTRAN LAPACK interface and the standard FORTRAN BLAS interface. If your LAPACK and BLAS interface consists of several libraries, use the path to the LAPACK library.

GCC Options

By default COMSOL Multiphysics uses the GCC libraries installed on the system. If COMSOL Multiphysics is unable to start, the software uses the GCC libraries shipped with COMSOL Multiphysics. The option -forcegcc is intended for use together with the LiveLink™ for MATLAB®; use it if you are unable to make function callbacks to MATLAB.

Application Options

The following options are used to specify inputs to an application with command-line options. Find more information about these options in the section The Application Argument Node in the Application Builder Reference Manual.

Table 22-20: COMSOL Target command-line arguments.
COMSOL Applications Options	Description
-appargnames <names>	Comma-separated list of argument names.
-appargvalues <values>	Comma-separated list of argument values.
-appargsfile <filename>	A file with arguments to the application. Each line in the file should have the format <name>=<value>.
-appargvarlist <names>	Comma-separated list of argument names whose values are on file.
-appargfilelist <filenames>	Comma-separated list of filenames. Each file contains the value for one argument.

COMSOL Commands

In additions to the options in Table 22-17, the standalone COMSOL command supports the following options on Linux.

Table 22-21: COMSOL command-line arguments.
COMSOL Options	Description
-open <file>	Open application
-run <file>	Run application

COMSOL Multiphysics Server Commands

Use a COMSOL Multiphysics server command to start a COMSOL process ready to process computational requests. A COMSOL Multiphysics server listens for TCP/IP connections from COMSOL Multiphysics clients. A COMSOL Desktop can become a COMSOL Multiphysics client by connecting to a COMSOL Multiphysics server. The LiveLink™ for MATLAB® also needs to connect to a COMSOL Multiphysics server.

The syntax for the COMSOL Multiphysics server command is

comsol [<options>] mphserver [<target arguments>]

The following target arguments are available for a COMSOL Multiphysics server command.

Table 22-22: COMSOL Target command-line arguments.
COMSOL Multiphysics Server Options	Description
-graphics	Start the server with graphics libraries. This displays plots on the server when you are connected with a client (that is, not with the COMSOL GUI).
-ipv6	Make COMSOL Multiphysics server listen on an IPv6 port.
-login {info} \| force \| never \| auto	Ask for login information. info means that only missing information is asked for. force resets the password. never requires that the login information is available. auto automatically creates a new username and password.
-mode batch \| {desktop}	Ignore Batch and Cluster Computing settings or use them as desktop settings.
-multi {auto} \| on \| off	Accept repeated client connections.
-passwd reset \| nostore	Specify that you want to provide a new password. To avoid storing the new password on file use <nostore>.
-port <port>	Specify a TCP/IP port to listen for connect attempts.
-portfile <path>	Specify that COMSOL Multiphysics writes its server port to the given <path> when it has started listening.
-silent	Do not listen to standard input.
-user <user>	Specify login name for a user.

Accessing the COMSOL Multiphysics Server Computer

To access the computer running the COMSOL Multiphysics server, log in on the server computer using ssh or a similar command and then enter the comsol mphserver command.

When you start a COMSOL Multiphysics server for the first time, you are asked for a username and password. Select a username and a password, which COMSOL then uses in communications between the COMSOL Multiphysics client and the server. You must also specify a matching username and password in the dialog. The software writes this login information in the subdirectory .comsol/v63/login.properties in your home directory.

Client–Server Security Issues

COMSOL Multiphysics can operate in a client–server mode where COMSOL Multiphysics runs as a separate client and a server. The COMSOL software uses a TCP/IP connection to send data between the server and the client.


	Always make sure that untrusted users cannot access the COMSOL login information. Protect the file .comsol/v63/login.properties in your home directory. This is important when using the COMSOL Multiphysics client–server configuration. Alternatively, start the COMSOL Multiphysics server with the -passwd nostore option, and clear the Remember username and password checkbox when connecting to the server. This ensures that your login information is not stored on file.

Once you start a COMSOL Multiphysics server, a person with access to your login information could potentially connect to your COMSOL Multiphysics server. When a COMSOL Multiphysics client connects or disconnects from a remote computer, the COMSOL Multiphysics server displays a message. The connection from the client to the server is made with the TCP protocol.

The server and client are mutually authenticated using a challenge handshake authentication protocol, which means that login information cannot be easily obtained by someone eavesdropping on the network communication. The TCP connection between the client and the server is otherwise not encrypted. If you require encryption of the TCP connection, you can use third-party software based on protocols such as SSH or IPSEC.

To enhance security, you can limit the address range that can access the COMSOL Multiphysics server, both in your firewall and by changing the COMSOL Multiphysics server configuration. To limit the allowed address range in the server, edit the file <COMSOL Installation Directory>/bin/conf/server.xml and find the lines:

<!-- To restrict access to the COMSOL server you can uncomment the block below.

and follow the instructions.

The default port for the COMSOL Multiphysics server is 2036. You can change this by using the option -port <port> when launching COMSOL and COMSOL Multiphysics server.

Documentation Security Issues

To serve the COMSOL Desktop with documentation, COMSOL Multiphysics opens a separate documentation server on the client computer when you open the documentation. The documentation server program, comsoldocserver.exe, is always installed, even when you choose online documentation. It is nontrivial to start the documentation server, so it is typically only started from comsol.exe or comsoldoc.exe.

To enhance security, you can limit the address range that can access the documentation server, both in your firewall and by changing the documentation server configuration. To limit the allowed address range in the server, edit the file <COMSOL Installation Directory>/doc/help/conf/server.xml and find the lines:

<!-- To restrict access to the documentation server you can uncomment the block below.

and follow the instructions. The default port for the documentation server when started from comsol.exe is 8090 or the nearest higher free port. You can change this by using the option -docport <docport> when launching COMSOL. The port used by the documentation server when started from comsoldoc.exe is 8390 or the nearest higher free port.

The communication via the COMSOL documentation server is not protected by a password or encrypted but can only access the locally installed COMSOL Multiphysics documentation. If you do not want the documentation server to access any locally installed data, use the online documentation.

Port Summary

The following table lists the default ports used by the COMSOL Multiphysics servers:

Table 22-23: Port Usage.
Port Number	Server	Description
2036	COMSOL Multiphysics server	For communication between the client and server when COMSOL Multiphysics operates in a client–server mode. The connection is password protected.
8090	Documentation server	Documentation server port when started from comsol.exe.
8390	Documentation server	Documentation server port when started from comsoldoc.exe.

COMSOL Multiphysics Client Commands

Use a COMSOL Multiphysics client command to start a COMSOL Desktop with the Connect to Server dialog open.

The syntax for the COMSOL Multiphysics client command is

comsol [<options>] mphclient [<target arguments>]

The following target arguments are available for a COMSOL Multiphysics client command:

Table 22-24: COMSOL Target command-line arguments.
COMSOL Multiphysics Client Options	Description
-open <file>	Open file.
-port <port>	Specify a TCP/IP port to connect to.
-server <server name>	Specify server to connect to.

COMSOL Batch Commands

Use the COMSOL batch command to run COMSOL jobs without a GUI. You can run both Model MPH files and model files for Java with the COMSOL batch command. Model files for Java need to be compiled before running.

The syntax for the COMSOL batch command is

comsol [<options>] batch [<target arguments>]

Its detailed target arguments are:

Table 22-25: COMSOL BATCH-specific arguments.
COMSOL Batch options	Description
-alivetime <seconds>	The time between writing status on disc.
-batchlog <filename>	File to store log in. If not used, the log appears in the command window.
-batchlogout	Log to standard out when storing on file.
-cancel	Stop the current solver without returning any data. See below.
-checklicense <filename>	Print license requirements for a Model MPH-file.
-classpathadd <classpath>	Additional classpath.
-clearmesh	Clear all meshes,
-clearsolution	Clear all solutions (except probe data),
-client	Run as client. If -mode is batch (the default), then the server that the client connects to should also be launched with -mode batch. Unless running in -mode desktop, the server must also be started with -mode batch.
-continue	Continue computing an interrupted batch job.
-createplots	Create default plots when running.
-dev <filename>	Path to a JAR-file with additional classes to call from the batch class file.
-error {on} \| off	Stop if an error occurs.
-external <process tag>	The external process target <process tag> for an operation.
-graphics	Start COMSOL batch with graphics libraries. This displays plots during analysis.
-host <hostname>	Connect to host <hostname>.
-inputfile <filename>	Run a Model MPH-file or class file. Also supports a model version location (dbmodel:/// URI) to run a model version stored in a Model Manager database. See Running COMSOL Batch with Models in Databases for more details.
-job <job tag>	The batch job to run. See The Job Option below.
-jobfile <filename>	Specify a text file using the following format: <inputfile0> <outputfile0> <inputfile1> <outputfile1> <inputfile2> <outputfile2> … If the filename <inputfile0> or <outputfile0> contains spaces, surround the path by double quotation marks ("..."). Each input-output pair will be run as a batch job consecutively. Other batch-specific options specified at the command line are applied to each of the listed jobs. In addition, the list can be updated continuously during the batch process.
-methodcall <tag> <filename>	Run a method call with the given tag. The file in <filename> contains the method call.
-mode {batch} \| desktop	Ignore Batch and Cluster Computing settings. See Ignoring Batch and Cluster Computing Settings above. If -mode is batch (the default), then the server that the client connects to should also be launched with -mode batch.
-norun	Do not compute the model. This option is useful if you, for example, just want to run -clearsolution or -clearmesh on a model that already includes a solution or mesh and then save it, without a solution or mesh, without computing the model first.
-nosave	Do not save the resulting model.
-operation progress\|cancel\| stop\|update\|clear\|rerun	The operation to run on the batch job.
-outputdir	Sets the location on the file system where output files produced by a batch run will be stored. If not used, the files will be stored in the same directory as the output model, or if the output model is stored in the database, in the standard batch directory (specified by the preference setting Computing > Cluster > Batch directory).
-outputfile <filename>	Save a Model MPH-file using the given filename. If output is not given, the input file is overwritten with the output. Also supports a model version location (dbmodel:/// URI) to save a model version to a Model Manager database. See COMSOL Batch under a Floating Network License for more details. Note that a class file as input cannot currently be combined with a model version location as output.
-paramfile <filename>	Table file containing parameter names in the first row and corresponding parameter value tuples in the following rows. That is, the parameter names should be on the first row (space separated), and the parameter values (if only one tuple) should be space separated on the second row. If you want to solve for more tuples, more rows are added in the same manner.
-pindex <parameter indices>	Comma-separated list of parameter indices (integers). The number of indices given has to correspond to the number of arguments given by -plist.
-plist <parameter value>	Comma-separated list of parameter values.
-pname <parameter name>	Comma-separated list of parameter names.
-port <port number>	Connect to port <port number.
-prodargs	Add extra command-line arguments using -prodargs followed by the arguments last in the call to COMSOL batch.
-recover	Recover and continue computation. See The Recover Option below.
-resethistory	Compact the history before saving. This argument can be useful, together with -clearmesh and -clearsolution, to reduce the size of the saved file.
-stop	Stop the current solver when it has finished, returning available data. See below.
-stoptime <time to stop>	Stop the batch job after a certain time (in seconds).
-study <study tag>	The study to compute. See The Study Option below.
-usebatchlic	Use batch license (requires batch licenses). See The Usebatchlic Option below.

Example

To use the COMSOL batch mode to solve a model, run the following command:

comsol batch -inputfile in.mph -outputfile out.mph -study std1

This command starts COMSOL Multiphysics in batch mode, solves the model in the Model MPH-file with the given filename using the active solver settings in the model, and stores the solution in the out.mph.

The Study Option

The -study option directs COMSOL Multiphysics to run a certain study. The study is identified by its tag. In the COMSOL Desktop, select under to see the tags of the jobs under within curly braces in the Model Builder. In the model object, determine the tags of the jobs by the command model.study().tags(). You can determine the name of each study by model.study(<tag>).name() using one of the job tags.

The Job Option

The -job option works similarly to the -study option. It directs COMSOL Multiphysics to start a certain job. The job is identified by its tag. In the model object, determine the tags of the jobs by the command model.batch().tags(). You can determine the name of each job by model.batch(<tag>).name() using one of the job tags.


	If the model uses an inner parametric solver (in a nested parametric sweep), the Job Configurations node is ignored by the batch job. In such cases, you need to switch to an outer parametric solver.

The Usebatchlic Option

The -usebatchlic option makes COMSOL use batch licenses for the job. This option is equivalent to the checkbox available in the and study nodes. For floating network licenses (FNL), a separate set of batch features are available for COMSOL Multiphysics and the licensed add-on products. Using batch licenses for a cluster computing or cluster sweep job means that you can continue working in the COMSOL Desktop locally while running batch jobs on remote computers and clusters using only a single FNL license.

Stopping and Canceling a Batch Job

You can stop a batch job using the following command:

comsol batch -stop <level> -inputfile <filename>

where <level> is the level to stop the process on. Set the level to a high value in order to stop as soon as possible. By default, it is set to 100. The -inputfile option indicates the filename of the model that another process is running. The inputfile arguments should be consistent with the one specified to launch another process. That is, either the same inputfile arguments should be provided or the -inputfile should be the same as the -outputfile specified to launch another process.

You can cancel a batch job using the following command:

comsol batch -cancel -inputfile <filename>

The -inputfile option indicates the filename of the model that another process is running. The inputfile arguments should be consistent with the one specified to launch another process. That is, either the same inputfile arguments should be provided or the -inputfile should be the same as the -outputfile specified to launch another process.

The Recover Option

For the -recover option, the working directory (where all .log, and .status files are generated) will contain the recovery file, which contains information about the recovery folder in the case that the COMSOL software stops working. If the -recover option is specified, the model from the recovery directory will be opened. If opening that model succeeds, a continue operation will be performed; otherwise, the input filename model will be simulated.

The COMSOL Compile Command

The comsol compile command compiles a model file for Java for use by the COMSOL batch command or for loading class files into the GUI. With the COMSOL Compiler, you can also use it to compile COMSOL applications into standalone executable applications. The Linux syntax for the COMSOL compile command is

comsol [<options>] compile [<target arguments>] <file>.java

The Java file is mandatory. The following optional target arguments are available:

Table 22-26: COMSOL Compile Options.
COMSOL compile Options	Description
-classpathadd <classpath>	Additional classpath
-jdkroot <path>	Path to the JDK root
-verbose	Verbose output

To compile an application in an MPH-file into a standalone executable application using COMSOL Compiler, use

comsol compile <full path to MPH-file> [<compile arguments>]


	Compiling applications requires a license for COMSOL Compiler™.

The following arguments are available:

Table 22-27: COMSOL compile arguments for Compiling Applications.
COMSOL compile Arguments	Description
-icon <path>	Path to image file for application icon.
-libraries cad,weatherdata	Optional data to include. Specify as a comma-separated list. CAD data is only applicable with the CAD Import Module or CAD LiveLink products. Weather data is only applicable with the Heat Transfer Module.
-outputdir <path>	Specify where the compiled application should be saved. The default is the directory where the application’s MPH-file is located.
-platforms windows,linux,macos	The platforms to compile for. Specify as a comma-separated list. The default is the platform where the compiler is run.
-runtime default \| ask \| <path>	Specify where to store the runtime when running the application. The default option is the platform’s default location. The ask option asks the user for the location of the runtime when running the application. The <path> option provides a location where the runtime should be unpacked and stored. Only specify a path when compiling for a single platform.
-runtimewindows <path>	Specify where the runtime should be unpacked on Windows.
-runtimelinux <path>	Specify where the runtime should be unpacked on Linux.
-runtimemacOS <path>	Specify where the runtime should be unpacked on macOS.
-runtimetype {download} \| embed	The type of runtime to include when compiling.
-splash <path>	Path to image file for splash screen.

Options not given are taken from the application’s node, except for -outputdir and -platforms.

COMSOL Cluster Commands

Use the comsol command with the option -nn <no. of nodes>. -nn specifies the total number of compute nodes created. A COMSOL instance resides in each compute node and communicates with other compute nodes using MPI. A compute node is a process running on the operating system, and multiple compute nodes can be assigned to run on a single host.


	See also Overview of Simulations on Shared- and Distributed-Memory Computers.

The syntax for the COMSOL cluster command is

comsol -nn <no. of nodes> [<options>] [<target>] [<target arguments>]

The following cluster commands are available:

Table 22-28: COMSOL Cluster Targets.
COMSOL cluster commands	Description
comsol -nn <nn> batch	Run a COMSOL batch job on a cluster in distributed mode.
comsol -nn <nn> mphserver	Run COMSOL Multiphysics server in distributed mode on a cluster, for interactive use from a COMSOL Multiphysics client.
comsol -nn <nn>	Run COMSOL Desktop in distributed mode interactively on a cluster.

The preferred way of starting COMSOL cluster jobs is from the Study node in the COMSOL Desktop. If you need to start COMSOL cluster jobs from the command line, the preferred way is to use the comsol -nn <nn> batch command because the comsol -nn <nn> mphserver and comsol -nn <nn> commands require TCP/IP access from your client computer to the cluster node where COMSOL runs.

There are several implementations of MPI. COMSOL Multiphysics is shipped with the Intel MPI library and a version of the MPICH library. The ARM version uses the MPICH library by default and does not include Intel MPI. COMSOL also supports most MPI implementations based on MPICH. It is recommended that you use the default MPI library.

The following options are available for clusters on Linux:

Table 22-29: COMSOL cluster options on Linux.
COMSOL Cluster options	Description
-clustersimple	Simple startup of cluster.
-f <path>	Path to hostfile.
-mpi {auto} \| intel \| intelmt \| mpich2 \| user \| path	MPI library to use. The Intel MPI libraries are not supported for ARM processors. The option can be used for troubleshooting. See Troubleshooting Distributed COMSOL with Intel MPI.
-mpiarg <arg>	MPI cluster-specific command arguments.1
-mpibootstrap {ssh} \| fork \| slurm \| ll \| lsf \| sge \| jmi	Set bootstrap server for Hydra.
-mpibootstrapexec <path>	Executable used by bootstrap server.
-mpidebug <debug level>	Set the MPI output level.
-mpienablex	Enable Xlib forwarding.
-mpifabrics fabric1:fabric2	Select network fabrics where fabric1 is one of <shm \| ofi>, and fabric2 is <ofi>. This option is not supported for ARM processors.
-mpihosts <hostnames>	MPI hosts. Use a comma-separated list of hostnames as <hostnames>.
-mpiio {on} \| off \| gpfs \| lustre \| panfs	Set the MPI I/O mode. Setting this property to off means that COMSOL does not search for a distributed file system. Setting this property to gpfs, lustre, or panfs makes COMSOL assume it is running on the selected file system. The arguments gpfs, lustre, and panfs are not supported for ARM processors.
-mpiofiprovider mlx \| tcp \| psm2 \| psm3 \| sockets \| efa \| rxm \| verbs	Choose an OFI (Open Fabrics Interface). This option is not supported for ARM processors.
-mpiofiroot <path>	Set path to Open Fabrics installation root. This option is not supported for ARM processors.
-mpipath <file>	MPI shared library file.
-mpirmk <pbs>	Select resource management kernel for a PBS scheduler. This option is not supported for ARM processors.
-mpiroot <path>	MPI library installation root path.
-nn <no. of nodes>	Number of compute nodes.
-nnhost <no. of nodes>	Number of compute nodes on each host.
-scalapack {auto} \| mkl \| scalapack \| user \| path	Scalapack library to use. For the path option, the environment variable COMSOL_SCALAPACK_PATH must be set. The argument mkl is not supported for ARM processors.
-scalapackpath <path>	Scalapack library path.

1 See Using an Installed MPI Library.

Running on Linux

COMSOL Multiphysics uses Hydra to initialize the MPI environment. To launch COMSOL Multiphysics with MPI, use the command line

comsol -nn <number of compute nodes> -f <filename>

The file <filename> should contain the hostnames of the physical nodes (or, alternatively, host) that you intend to use. You can find out the hostname of each physical node from the hostname command. Each physical node should be listed on a separate line in the file. You can also list the IP address of each physical node. The file can contain more hosts than you intend to use.

•

You can set the remote node access mechanism that is used for connecting using the switch -mpibootstrap. The valid options are ssh, rsh, fork, slurm, ll, lsf, sge, and jmi. This is important if the cluster only supports a different remote node access mechanism than ssh because ssh is the default protocol used.

•

Use the switch -mpibootstrapexec to set the path to the remote node access mechanism such as /usr/bin/ssh.

•

The option -mpidebug sets the output level from MPI. The default is level 4.

•

You can control the network fabrics used for communication with the option -mpifabrics fabric1:fabric2, where fabric1 is one of shm or ofi, and fabric2 is ofi. The option -mpiofiprovider controls the network provider used by the OFI (Open Fabrics Interfaces). The options are the following: mlx, tcp, psm2, psm3, sockets, efa, rxm, or verbs. Use these options if you are having trouble with the default fabrics used. This option is not supported for ARM processors.

•

Use -mpienablex to enable Xlib forwarding. Xlib forwarding is off by default.

Previously there was a shorthand for performing the COMSOL MPI environment initialization and starting COMSOL Multiphysics. The -clustersimple option is still supported but performs the same Hydra MPI initialization as other COMSOL command with cluster options specified. For example,

comsol -clustersimple batch -inputfile input.mph -outputfile output.mph

is equivalent to the following command when the specified number of compute nodes is 4:

comsol -nn 4 batch -inputfile input.mph -outputfile output.mph

So when no COMSOL cluster options are included in the command, the use of -clustersimple instructs the Intel MPI library to automatically detect the number of nodes that were scheduled to the program. However, explicitly setting the number of processes with the -nn option is common practice, as COMSOL Multiphysics can combine MPI with multithreading to obtain more efficient performance. The -nn option will override some of the effects that the -clustersimple option has.

Starting Distributed COMSOL — Linux Examples

Make sure that COMSOL Multiphysics is able to start on all nodes where you intend to run it.


	Each node requires access to the license manager. If the node is unable to check out a license, it aborts the startup process.

The following three examples show the command for starting distributed computing with COMSOL Desktop, COMSOL Multiphysics server, and COMSOL batch mode, respectively. Each starts 4 computational nodes, one on each of the 4 hosts listed in the file hostfile:

comsol -nn 4 -f hostfile

comsol -nn 4 -f hostfile mphserver

comsol -nn 4 -f hosts batch -inputfile in.mph -outputfile out.mph

It is possible to specify the number of CPU cores for each COMSOL process. The following command uses the option -np 2 to assign 2 CPU cores to each compute node:

comsol -nn 4 -np 2 -f hostfile

It is also possible to have more compute nodes than hosts. The following command initializes 8 compute nodes, assigning 2 compute nodes to each host:

comsol -nn 8 -nnhost 2 -f hostfile

For additional command-line options, see COMSOL Cluster Options in Table 22-29.

Cluster Computing Study

Additionally, the COMSOL MPI arguments are configurable inside the COMSOL start script. To configure COMSOL to work with a job scheduler through the Cluster Computing study, you can set the options

-Dcs.precmd=<Command line>

-Dcs.postcmd=<Command line>

in the comsol.ini file. This configuration adds commands prior to the comsol command and after the comsol command. You can add {nn} or {perhost} to any of these pre- or postcommands. These additions configure the Cluster Computing study to use the number of nodes and number of nodes on each host from the corresponding settings for the Cluster Computing study. For more information, see Cluster Computing.

Using an Installed MPI Library

COMSOL Multiphysics ships with the Intel MPI library and a version of MPICH library. COMSOL should work with most MPICH-ABI compatible libraries. To download the latest version of Intel MPI library runtime visit https://software.intel.com/en-us/intel-mpi-library. To run COMSOL Multiphysics with another version of Intel MPI or other MPI library, set -mpiroot to the root path of the MPI library. In case the downloaded library is not compatible with the version COMSOL Multiphysics uses (this should usually not be the case), also set -mpipath to the dynamically loaded library that should be used.

For running COMSOL Multiphysics with an installed MPICH library, the COMSOL software also has a compatibility mode that you can activate by adding the option -mpi mpich2. When using this option, both the variables PATH and LD_LIBRARY_PATH must include your MPI implementation. It is also possible to use other MPI libraries based on MPICH using the option -mpipath <path to shared library> and -mpiroot <path to root of mpi library installation>. Table 22-17 lists the MPI-related options: -mpi, -mpipath, -scalapack, and -scalapackpath. To use the MPICH library shipped with COMSOL you do not need to set -mpiroot, just specify -mpi mpich2.

Troubleshooting Distributed COMSOL

The following syntax can be used to troubleshoot the Intel MPI library environment without running a COMSOL Multiphysics model:

comsol [<options>] hydra [<Hydra command>] [<target arguments>]

Table 22-30: COMSOL Hydra COMMANDS.
COMSOL hydra COMMANDS	Description
cpuinfo	Run cpuinfo command1
fiinfo	Run fi_info command1
fipingpong	Run fi_pingpong command1
killjobs	Run parakill command
help	Run help command
mpitest	Run a distributed test program1
tune	Run mpitune command1
tunefast	Run mpitune_fast command1

1 Only supported for Intel MPI.

Use a call like the following, for example, for more information about each command: comsol hydra cpuinfo.

Troubleshooting Distributed COMSOL with Intel MPI

The default of the Intel MPI library is to use ssh as communication protocol. If you require another communication protocol, use the option -mpibootstrap <protocol>. If you are using a scheduler, the Intel MPI library can often detect the environments it is running in automatically, in which case you may not need to provide additional cluster options in the COMSOL command.

•

If you are using a PBS-based scheduler, add -clustersimple or -mpirmk pbs to the command line in order for Intel MPI to interpret the environment correctly.

•

If you are using an LSF-based scheduler, -clustersimple or -mpirmk lsf to the command line in order for Intel MPI to interpret the environment correctly.

•

The Intel MPI library automatically tries to detect the best option for communication and uses InfiniBand if it detects it. To verify that COMSOL is using InfiniBand, check the output from the startup of COMSOL with -mpidebug 10; it should not mention TCP transfer mode.

•

If you have problems with correct selection of your network card, add the -mpiofiprovider <network type> option to the command line.

•

The -mpiofiprovider sockets option selects general TCP network communication and can be used for finding out if there is some problem in the Open Fabrics interface stack of the machine.

•

Use the -mpi mpich2 option to switch from the default Intel MPI library to the MPICH2 library.

In some cases it helps if you combine the -mpiofiprovider option with the environment variable PSM_SHAREDCONTEXTS_MAX set to 1. You can control the fabrics used for communication with the option -mpifabrics fabric1:fabric2, where fabric1 is equal to fabric2 or fabric1 is shm. Additionally, the -mpiofiprovider option controls the fabric provider.

If COMSOL Multiphysics aborts during start, make sure that all nodes can access the license manager and that COMSOL Multiphysics can be started on each node when not running distributed. Sometimes there is additional information in the log files located in $HOME/.comsol/v63/configuration/comsol/*.log. If this does not help, start the MPI test program to make sure that the MPI library is working as it should using the following command:

comsol -nn <number of nodes> -f <hostfile> hydra mpitest

For more verbose information about the startup process when using Hydra, use -mpiarg -verbose, or set -mpidebug to a value greater than the default 0.

COMSOL MATLAB Command

Use the COMSOL matlab command to access the COMSOL API through MATLAB®. Enter:

comsol mphserver matlab [<options>]

which launches a COMSOL Multiphysics server in a console window, starts MATLAB, and connects MATLAB to the COMSOL Multiphysics server.

The following options are available for the comsol mphserver matlab command:

Table 22-31: COMSOL MATLAB options.
COMSOL MATLAB options	Description
-desktop	Start with Desktop.
-graphics	Start the server with graphics libraries. This enables plotting on the server. Available only when running comsolmphserver matlab [<options>].
-host <hostname>	Connect to host.
-mlnosplash	Start without MATLAB splash screen.
-mlroot <path>	MATLAB installation directory.
-mlstartdir <path>	Start in directory path <path>.
-nodesktop	Start without Desktop.
-port <hostname>	Connect to port.

The comsol trust Command

Use the comsol trust command to trust methods used in add-ins. The following commands are supported:

•

comsol trust list, to list the content of the trust store.

•

comsol trust add -addinmethods <path_to_addin> [<method_name1> ...], to trust the listed methods for an add-in. If no methods are given, all methods in the add-in are trusted. A TrustID is created for the trusted methods

•

comsol trust revoke <TrustID>, to revoke the trust in the methods for the named TrustID.