COMSOL Commands on macOS
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 following table lists the command and targets:
Requires LiveLinkfor MATLAB® license
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 maci64 and macarm64 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).
-alloc {native} | scalable
-blas {auto} | mkl | veclib | armpl | openblas | blas | path
BLAS library to use.3 mkl is supported for Intel processors. openblas and armpl is supported for Apple silicon.
-c <path>
-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.
-docroot <path>
-memoptassem {off} | matrix | vector | on
-mpmode throughput | turnaround | owner
-np <no. of cores>
-tmpdir <path>
-v, -version
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 the COMSOL Multiphysics software 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.
Shared-Memory Options
Use the option -np to control the number of core and processors used. The default is to use all available cores and processors.
Depending on how loaded your machine is, you can control how COMSOL Multiphysics uses the available processors. The following options are available:
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 the use of the scalable allocators as preferences on the Computing>Multicore page in the Preferences dialog box. To specify the number of cores manually, select the Number of cores check box to enter a number in the associated text field. By default, all cores are used. 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 check box 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 check box. 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-35: COMSOL BLAS Options.
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.
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.
-appargsfile <filename>
-appargfilelist <filenames>
COMSOL Commands
In additions to the options in Table 22-17, the standalone COMSOL command supports the following options on macOS:
-open <file>
-run <file>
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:
-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.
-multi {auto} | on | off
-port <port>
-user <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 server command.
Login Information
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 the COMSOL software then uses in communications between the COMSOL Multiphysics client and the server. You must also specify a matching username and password on the settings page in the Model Navigator, which opens when you start the COMSOL Multiphysics client. The software writes this login information in the file login.properties. The login information is located in Library/Preferences/COMSOL/v62/login.properties in your home directory.
Client–Server Security Issues
COMSOL can operate in a client–server mode where COMSOL Multiphysics runs as a separate client and a server. COMSOL 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 Library/Preferences/COMSOL/v62/login.properties. 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 check box 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 opens a separate documentation server on the client computer when you open the documentation.
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 is 8090. You can change this by using the option -docport <docport> when launching COMSOL Multiphysics.
COMSOL Multiphysics Client Commands
Use a COMSOL Multiphysics client command to start a COMSOL Desktop with a the Connect to Server dialog box 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.
-open <file>
-port <port>
-server <server name>
COMSOL Batch Commands
Use the COMSOL batch command to run COMSOL jobs without a user interface. 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:
-alivetime <seconds>
-batchlog <filename>
-checklicense <filename>
-classpathadd <classpath>
-dev <filename>
-external <process tag>
The external process target <process tag> for an operation.
-host <hostname>
Connect to host <hostname>.
-inputfile <filename>
-job <job tag>
-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 ("...").
-methodcall <tag> <filename>
Run a method call with the given tag. The file in <filename> contains the method call.
-mode {batch} | desktop
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.
-outputfile <filename>
-paramfile <filename>
-pindex <parameter indices>
-plist <parameter value>
-pname <parameter name>
-port <port name>
Connect to port <port name>.
Add extra command-line arguments using -prodargs followed by the arguments last in the call to COMSOL batch.
Compact the history before saving. This argument can be useful, together with -clearmesh and -clearsolution, to reduce the size of the saved file.
-stoptime <time to stop>
-study <study tag>
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.
Example
To use the COMSOL Multiphysics software in batch mode to solve a model, run the following command:
comsol batch -inputfile in.mph -outputfile out.mph -study std1
This command starts COMSOL 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 Show Name and Tag under Model Builder Node Label to see the tags of the jobs under Study 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 similar 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.
The Usebatchlic Option
The -usebatchlic option makes COMSOL use batch licenses for the job. This option is equivalent to the Use batch license check box available in the Cluster Computing and Cluster Sweep 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.
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 macOS 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‘
-classpathadd <classpath>
-jdkroot <path>
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>]
The following arguments are available:
-icon <path>
-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.
-splash <path>
Options not given are taken from the application’s Compiler node, except for -outputdir and -platforms.
COMSOL MATLAB Command
Use the COMSOL MATLAB command to access the COMSOL API through MATLAB. Type:
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:
-host <hostname>
-mlroot <path>
-port <hostname>
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.