Difference between revisions of "HowTo:matlab"

From CAC Wiki
Jump to: navigation, search
(→‎MATLAB)
 
(18 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
= MATLAB =
+
= MATLAB (obsolete) =
  
 
This is a short help file on using the high-level language code "Matlab" on our machines.  
 
This is a short help file on using the high-level language code "Matlab" on our machines.  
  
−
'''<u>Important</u>: The Centre for Advanced Computing does currently not have a stand-alone Matlab license. This means that users who wish to use MATLAB on our systems have to provide a valid license. This may require a connection to an external license server, or the purchase of a local license file.
+
<span style="color:#ff00ff">'''<u>Important</u>: Pleased note that this file does not reflect the current licensing / installment of MATLAB at the Centre for Advanced Computing. It is kept for Documentation purposes only. Refer to the [[Software:matlab|current help file]] for accurate information.</span>
  
 
The software is only made available to persons who belong to a specific Unix group. See details below.
 
The software is only made available to persons who belong to a specific Unix group. See details below.
Line 11: Line 11:
 
== Features ==
 
== Features ==
  
−
The "General Atomic and Molecular Electronic Structure System" (GAMESS) is a quantum chemistry software package that was assembled from various older codes (in particular, HONDO) by M. Dupuis, D. Spangler, and J. J. Wendoloski of the National Resources for Computations in Chemistry (NRCC). The code has undergone great changes since then and is maintained now by the Gordon Research Group at Iowa State University.
+
From the Matlab web page:  "MATLAB® is a high-level technical computing language and interactive environment for algorithm development, data visualization, data analysis, and numeric computation. [...] You can use MATLAB in a wide range of applications, including signal and image processing, communications, control design, test and measurement, financial modeling and analysis, and computational biology. Add-on toolboxes (collections of special-purpose MATLAB functions, available separately) extend the MATLAB environment to solve particular classes of problems in these application areas."
  
−
Gamess performs a great many of standard quantum chemical calculations. These include:
+
Here is a list of features, also from the webpage:
 +
* High-level language for technical computing
 +
* Development environment for managing code, files, and data
 +
* Interactive tools for iterative exploration, design, and problem solving
 +
* Mathematical functions for linear algebra, statistics, Fourier analysis, filtering, optimization, and numerical integration
 +
* 2-D and 3-D graphics functions for visualizing data
 +
* Tools for building custom graphical user interfaces
 +
* Functions for integrating MATLAB based algorithms with external applications and languages, such as C, C++, Fortran, Java, COM, and Microsoft Excel
 +
* The full Matlab program and most Toolboxes are installed on our systems, but '''the license for their usage is supplied by the user.'''
  
−
* RHF, UHF, ROHF, GVB, or MCSCF self-consistent calculations.
+
== Location and Setup ==
−
* CI or MP2 corrections to the energy.
+
−
* Semi-empirical MNDO, AM1, or PM3 methods.
+
−
* Analytic energy gradients for SCF, MP2 or CI.
+
−
* Geometry optimizations, saddle point searches, and vibrational frequencies.
+
−
* Intrinsic reaction paths, gradient extremal curves, and dynmic reaction coordinates.
+
−
* Many molecular properties, such as densities, electrostatic potentials, dipole moments, etc.
+
−
* Modelling of solvent effects and electric fields.
+
−
For a complete list of capabilities of GAMESS, consult [http://www.msg.ameslab.gov/gamess/capabilities.html this table] or look at [http://www.msg.ameslab.gov/gamess/documentation.html the Gamess documentation].
+
  
−
Gamess is described in ''General Atomic and Molecular Electronic Structure System''; M.W.Schmidt, K.K.Baldridge, J.A.Boatz, S.T.Elbert, M.S.Gordon, J.H.Jensen, S.Koseki, N.Matsunaga, K.A.Nguyen, S.Su, T.L.Windus, M.Dupuis, J.A.Montgomery; ''J. Comput. Chem.'' '''14''', 1347-1363 (1993)
+
The present version of Matlab is R2014a for Linux. The programs in the Matlab package are located in the directory /opt/matlab. Matlab processes should only be run in batch mode through our Gridengine scheduler.
  
−
and  
+
Note that many of the Matlab Toolboxes are installed on our clusters. Users who have a pre-existing Matlab license can submit and run '''serial''' Matlab jobs on our cluster nodes. '''We do not hold a so-called DCS (Distributed-Compute Server) license''' and can therefore not run parallel MATLAB jobs.
  
−
''Advances in electronic structure theory: GAMESS a decade later''; M.S.Gordon, M.W.Schmidt pp. 1167-1189 in ''Theory and Applications of Computational Chemistry: the first forty years''; C.E.Dykstra, G.Frenking, K.S.Kim, G.E.Scuseria (editors), Elsevier, Amsterdam, 2005.
+
It is [http://cac.queensu.ca/wp-content/files/cac-matlab-statement.pdf required that you sign a statement] if you want to use MATLAB. We will confirm this statement, and you will then be made a member of a Unix group "matlab", which enables you to access the software. Contact us if you are in doubt of whether you will be able to run Matlab on our system.
  
−
== Location of the program and setup ==
+
To set the proper environment variables and include the directories with the binaries in your PATH, you should type:
  
−
The program resides in '''/opt/gamess''' and is called '''gamess.01.x'''. You also find some test examples in the program directory, which are useful to get an idea of the input format for the program. You are '''not''' allowed to copy the executable or any part of the distribution onto your local machine. However you can easily obtain the program yourself. See the [http://www.msg.ameslab.gov/gamess/download.html GAMESS source code distribution page].
+
<pre>use matlab</pre>
  
−
Unlike other programs, no special setup is needed to run Gamess. All environment variables etc. are set with an execution script that will be described in the next section. However, it is a good idea to put the directory with the Gamess program into the path, i.e. set the PATH environment variable. This is best done through the usepackage utility, simply by typing <pre>use gamess </pre>
+
To avoid having to do this before every Matlab session, you may also include this command in your setup file, e.g. .bash_profile.
 +
Finally you may have to point an environment variable LM_LICENSE_FILE to the proper license file:
  
−
== Scratch files ==
+
<pre>export LM_LICENSE_FILE=lic_file</pre>
  
−
When you run Gamess a '''scratch space directory''' is set to '''/scratch/$USER''' and all temporary files and intermediate output will be placed in that directory. The program also requires a '''local temporary directory''' right below your home directory called '''$USER/scr'''. Make sure that you move files that you want to keep from there before running Gamess again with the same case_name. The second run requires that some temporary files be removed before re-run and will fail if they are still present in the scratch directory. For instance, if your username is "hpc9876", you will need "/scratch/hpc9876" and "/home/hpc9876/scr". Note that the former is automatically created when you obtain an account, but the latter has to be made by you explicitly.
+
Here lic_file stands for the full path and file name of your license file. You need to make sure that the latter cannot be accessed by anyone but you. This command may of course also be placed into a setup file to avoid retyping.
 +
 
 +
Since the Matlab licenses are specific to the user (as the user is who supplies them), it is possible that specific set-ups are required, and the simple "use" command won't work. In this case, please get in touch and we modify the set-up to work with your specific case.
 
|}
 
|}
 +
 
{|  style="border-spacing: 8px;"
 
{|  style="border-spacing: 8px;"
 
| valign="top" width="50%" style="padding:1em; border:1px solid #aaaaaa; background-color:#f7f7f7; border-radius:7px" |
 
| valign="top" width="50%" style="padding:1em; border:1px solid #aaaaaa; background-color:#f7f7f7; border-radius:7px" |
  
−
== Running Gamess from a command line==
+
== Running from a command line==
  
−
To run Gamess, a script file '''rungms''' is used. This file resides in the same directory as the '''gamess.00.x''' executable. Assuming that the home of the script file and executable is in your path, all you need to do is type
+
The core of Matlab is a high-level programming language and an interactive programming/computing environment. Since you have to be a licensed user of Matlab to run Matlab programs on our machines, it is possible for you to either allow us access to an external license server, or to move your license file to our systems. In either case, you are responsible for maintaining the license.
−
<pre>rungms case_name 01 n_procs</pre>
+
−
where case_name is the name of the input file (file extension is assumed to be .inp and must not be specified), and n_procs stands for the number of processes to be used in a parallel Gamess run. If n_procs=1 a serial run will be performed.  
+
  
−
'''Note:''' It is absolutely essential to have a good idea about the size and complexity of your calculations before you start a Gamess job. Many of the methods have terrible scaling properties, i.e. the computational cost grows very quickly with the number of electrons, degrees of freedom, or number of basis functions used. We suggest you start with a small basis set and a cheap method, and then slowly increase those parameters.
+
Here, we discuss how to run an interactive Matlab session on one of our servers such as the workup/login node swlogin1. We assume that you are included in the "matlab" Unix group, and therefore have proper access to /opt/matlab where the software resides.  
  
−
Like most programs, Gamess requires an '''input (.inp) file''' that describes the system (usually a molecule) for which the calculation will be performed, specifies the level of calculation (eg, CISD), and provides other necessary information (starting orbitals, basis sets, required properties, etc). The format of the input is considerably more demanding than the one required for Gaussian (another widely used electronic-structure program), and much less information is hidden inside of defaults. This makes Gamess a very flexible program, but increases the risk of doing something wrong. Careful study of example input files and the documentation is required to run Gamess successfully. This is particularly true for CI or CAS-SCF calculations.
+
Once Matlab usage is set up properly, you only need to type
 +
<pre>matlab</pre>
 +
to start the GUI of the Matlab programming environment. Issuing the command with the ''-nodisplay'' will give you a command-line version that does not use the GUI.
  
−
Once an input file is prepared, you will have to make the decision if you want to run Gamess in serial or in parallel mode. Gamess supports the use of multiple processors. However, the scaling (ie, the efficiency of parallel processing) varies with the type of calculation and the systems. We suggest you perform a small test calculation of the same type as your production calculation (eg, with a minimal basis set), and rerun it several times with a varying number of processors. Compare the timings and use the maximum number of processors that yield acceptable scaling for your production calculation.
+
== Batch jobs ==
  
−
== Submitting (parallel) Gamess jobs ==
+
In many cases, you will run Matlab in '''batch mode'''. Interactive work should be done elsewhere, whereas the computationally more intensive runs could be executed on our clusters.
  
−
Gamess has to be run via the Grid Engine, which is a load-balancing program that submits batch jobs to low-load processors on the cluster cluster. [[HowTo:Scheduler|To learn more about this program, click here]]. A Gamess job is submitted to the Grid Engine in the form of an execution script. A reasonable execution script for Gamess looks like this:
+
Production jobs on our clusters '''must be''' submitted via the scheduler Grid Engine. To obtain details, [[HowTo:Scheduler|read our Help File]]. For a Matlab batch job, this means that you have to prepare a job script and you have to call Matlab without the Graphical User Interface. If you encounter issues with preparing such a script, please contact us for assistance.
−
 
+
−
<pre>
+
−
#$ -S /bin/bash
+
−
#$ -q abaqus.q
+
−
#$ -l qname=abaqus.q
+
−
#$ -cwd
+
−
#$ -V
+
−
#$ -m be
+
−
#$ -M {your email address}
+
−
#$ -o {standard output file}
+
−
#$ -e {standard error file}
+
−
#$ -pe shm.pe {number of processors}
+
−
rungms {case name} 01 $NSLOTS
+
−
</pre>
+
−
 
+
−
In this template, just replace all entries enclosed in curly brackets by the proper values (do '''not''' retain the brackets. The lines starting with "#$ -o" and "#$ -e" define the standard output and standard error files, respectively.
+
−
 
+
−
The lines containing "abaqus.q" are there to force execution on the Linux (SW) cluster. Although we have a running version of the code on the legacy Solaris platform (M9000) server, we recommend to retain these lines and execute under Linux because of a likely better performance. In some special cases (for instance, very large memory requirements), it may be better to execute under Solaris. In that case you should remove the two lines with "abaqus.q" in it.
+
−
 
+
−
Note that all lines starting with "#$" are directives for the Grid Engine, and will be interpreted when the script is submitted to that program. The "#$ -V" and "#$ -cwd" instruct the executing shell of the script to inherit the environment of the calling shell (for instance the path), and set the starting directory to the current working directory, respectively.  
+
−
 
+
−
You also need to specify the name of the input file just like in an interactive run. The input file is supposed to have "file extension" .inp and reside in the same directory as the Grid Engine script. The extension should not be specified, i.e. if the case name is "mycase", the program will read in from a file called "mycase.inp".
+
−
 
+
−
The number of processes is specified in the "#$ -pe" line, which instructs the Grid Engine to allocate the proper number of CPUs for your run. You do not have to specify it separately in the rungms command line, because Grid Engine sets the environment variable $NSLOTS properly.
+
−
 
+
−
Assuming your Grid Engine script is called "gamess.sh", it is submitted to GridEngine by typing
+
−
<pre>qsub gamess.sh</pre>
+
−
No further specification of the output is necessary, since this is done inside the script and handled by GridEngine.
+
 
|}
 
|}
 
{|  style="border-spacing: 8px;"
 
{|  style="border-spacing: 8px;"
 
| valign="top" width="50%" style="padding:1em; border:1px solid #aaaaaa; background-color:#e1eaf1; border-radius:7px" |
 
| valign="top" width="50%" style="padding:1em; border:1px solid #aaaaaa; background-color:#e1eaf1; border-radius:7px" |
−
 
−
== Licensing ==
 
−
 
−
Gamess is a licensed program although it is distributed freely. The license held by the Centre for Advanced Computing is limited to our computers at our main site. That means that any of our users can use the program on our machines (but nowhere else), whether they are located at Queen's or not. You are '''not''' allowed to copy the executable or any part of the distribution onto your local machine. However you can easily obtain the program yourself. See the [http://www.msg.ameslab.gov/gamess/download.html GAMESS source code distribution page]. Gamess is a very portable program, and will run on IBM PC's (Windows), on a Mac, a variety of Unix platforms (including Linux), and your cellphone (just kidding).
 
−
 
−
Before you can access the Gamess executables and run the program, you have to read the license agreement that exists between the Gamess distributors and HPCVL. You also have to [http://www.hpcvl.org/sites/default/files/hpcvl%20gamess_statement.pdf sign a statement] that you have done so, and return it to us (fax to (613) 533-2015 or scan/email to cac.admin@queensu.ca).
 
  
 
== Where can I get more detailed information ? ==
 
== Where can I get more detailed information ? ==
−
Gamess is not a simple program to run. It requires careful study of the input format, and a certain degree of knowledge about the "nuts and bolts" of computational quantum chemistry.  
+
Matlab is a complex software package, and requires some practice to be used efficiently. In this FAQ we can not explain its use in any detail.  
  
−
* It is impossible to use the program efficiently without reading the [http://www.msg.ameslab.gov/gamess/documentation.html user documentation]. 
+
* MATLAB features a complete set of online-documentation that may be accessed from inside the GUI by selecting the Help tab.
−
* There is an official [http://www.msg.ameslab.gov/gamess/index.html Gamess homepage] with some information about capabilities of program, donloading a copy yourself, and the history of Gamess.
+
* There are also a Getting Started Tutorial and various Demos.
 +
* Online documentation is also available at [http://www.mathworks.com/help/matlab/ http://www.mathworks.com/help/matlab/].
 +
* If you have problems with the GridEngine, [[HowTo:Scheduler|read our help file on that subject]]
 
* '''[mailto:cac.help@queensu.ca Send email to cac.help@queensu.ca]'''. We're happy to help.
 
* '''[mailto:cac.help@queensu.ca Send email to cac.help@queensu.ca]'''. We're happy to help.
 
|}
 
|}

Latest revision as of 19:51, 30 May 2017

MATLAB (obsolete)

This is a short help file on using the high-level language code "Matlab" on our machines.

Important: Pleased note that this file does not reflect the current licensing / installment of MATLAB at the Centre for Advanced Computing. It is kept for Documentation purposes only. Refer to the current help file for accurate information.

The software is only made available to persons who belong to a specific Unix group. See details below.

Features

From the Matlab web page: "MATLAB® is a high-level technical computing language and interactive environment for algorithm development, data visualization, data analysis, and numeric computation. [...] You can use MATLAB in a wide range of applications, including signal and image processing, communications, control design, test and measurement, financial modeling and analysis, and computational biology. Add-on toolboxes (collections of special-purpose MATLAB functions, available separately) extend the MATLAB environment to solve particular classes of problems in these application areas."

Here is a list of features, also from the webpage:

  • High-level language for technical computing
  • Development environment for managing code, files, and data
  • Interactive tools for iterative exploration, design, and problem solving
  • Mathematical functions for linear algebra, statistics, Fourier analysis, filtering, optimization, and numerical integration
  • 2-D and 3-D graphics functions for visualizing data
  • Tools for building custom graphical user interfaces
  • Functions for integrating MATLAB based algorithms with external applications and languages, such as C, C++, Fortran, Java, COM, and Microsoft Excel
  • The full Matlab program and most Toolboxes are installed on our systems, but the license for their usage is supplied by the user.

Location and Setup

The present version of Matlab is R2014a for Linux. The programs in the Matlab package are located in the directory /opt/matlab. Matlab processes should only be run in batch mode through our Gridengine scheduler.

Note that many of the Matlab Toolboxes are installed on our clusters. Users who have a pre-existing Matlab license can submit and run serial Matlab jobs on our cluster nodes. We do not hold a so-called DCS (Distributed-Compute Server) license and can therefore not run parallel MATLAB jobs.

It is required that you sign a statement if you want to use MATLAB. We will confirm this statement, and you will then be made a member of a Unix group "matlab", which enables you to access the software. Contact us if you are in doubt of whether you will be able to run Matlab on our system.

To set the proper environment variables and include the directories with the binaries in your PATH, you should type: 

use matlab

To avoid having to do this before every Matlab session, you may also include this command in your setup file, e.g. .bash_profile. Finally you may have to point an environment variable LM_LICENSE_FILE to the proper license file: 

export LM_LICENSE_FILE=lic_file

Here lic_file stands for the full path and file name of your license file. You need to make sure that the latter cannot be accessed by anyone but you. This command may of course also be placed into a setup file to avoid retyping.

Since the Matlab licenses are specific to the user (as the user is who supplies them), it is possible that specific set-ups are required, and the simple "use" command won't work. In this case, please get in touch and we modify the set-up to work with your specific case.

Running from a command line

The core of Matlab is a high-level programming language and an interactive programming/computing environment. Since you have to be a licensed user of Matlab to run Matlab programs on our machines, it is possible for you to either allow us access to an external license server, or to move your license file to our systems. In either case, you are responsible for maintaining the license.

Here, we discuss how to run an interactive Matlab session on one of our servers such as the workup/login node swlogin1. We assume that you are included in the "matlab" Unix group, and therefore have proper access to /opt/matlab where the software resides.

Once Matlab usage is set up properly, you only need to type 

matlab

to start the GUI of the Matlab programming environment. Issuing the command with the -nodisplay will give you a command-line version that does not use the GUI.

Batch jobs

In many cases, you will run Matlab in batch mode. Interactive work should be done elsewhere, whereas the computationally more intensive runs could be executed on our clusters.

Production jobs on our clusters must be submitted via the scheduler Grid Engine. To obtain details, read our Help File. For a Matlab batch job, this means that you have to prepare a job script and you have to call Matlab without the Graphical User Interface. If you encounter issues with preparing such a script, please contact us for assistance.

Where can I get more detailed information ?

Matlab is a complex software package, and requires some practice to be used efficiently. In this FAQ we can not explain its use in any detail.

Retrieved from ‘https://info.cac.queensu.ca/wiki/index.php?title=HowTo:matlab&oldid=1450’