Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
running_molpro [2021/04/19 08:30] – fix/update xml-orbdump dollrunning_molpro [2024/01/08 13:24] (current) – external edit 127.0.0.1
Line 1: Line 1:
 +====== Running Molpro ======
 +
 +On Unix systems, Molpro is accessed using the //molpro// unix command. The syntax is
 +
 +''molpro'' //options// //datafile//
 +
 +Molpro’s execution is controlled by user-prepared data; if //datafile// is not given on the command line, the data is read from standard input, and program results go to standard output. Otherwise, data is taken from //datafile,// and the output is written to a file whose name is generated from //datafile// by removing any trailing suffix, and appending ''.out''. The name //datafile// must not contain parenthesis, brackets, or other special characters like exclamation marks (!), question marks (?), slashes (/), backslashes (\), blanks( ), equality signs($=$), commas (,), semicolons (;), asterisks (*), or any kind of quotes. If the output file already exists, then the old file is appended to the same name with suffix ''.out_1'', and then deleted. This provides a mechanism for saving old output files from overwriting. Note that the above behaviour can be modified with the ''-o'' or ''-s'' options.
 +
 +For example, a serial Molpro calculation is started using
 +
 +''%%molpro mymolecule.inp%%''
 +
 +and this creates an output ''mymolecule.out''. For larger calculations, it may be necessary to specify how much dynamic (stack) memory molpro can allocate, using the ''-m'' option:
 +
 +''%%molpro -m100 mymolecule.inp%%''
 +
 +This allocates 100 MW (megawords) of stack memory. Further options are necessary for parallel excution, see section [[running Molpro on parallel computers#specifying parallel execution|specifying parallel execution]]. For parallel excutions, it is very important to read and understand also sections [[running Molpro on parallel computers#GA Installation notes|GA Installation notes]] and [[running Molpro on parallel computers#memory specifications|memory specifications]].
 +
 +===== General Options =====
 +
 +Most options are not required, since sensible system defaults are usually set. Options as detailed below may be given, in order of decreasing priority, on the command line, in the environment variable MOLPRO_OPTIONS, or in the files ''%%./molpro.rc%%'', ''%%$HOME/.molprorc%%'', and ''tuning.rc'' in the library files directory.
 +
 +  * **''-o'' $|$ ''%%--output%%'' //outfile//** [option:o] specifies a different output file.
 +  * **''-d'' $|$ ''%%--directory%%'' //directory//** specifies the scratch directory for the program.
 +  * **''%%--backup%%'' //nfile//** enables the saving of previous output files, up to a maximum of  //nfile//. If //nfile// is omitted, it defaults to infinity. The names of the backup files are constructed by appending ''_'' and a sequence number to the output file name, and both regular and xml-format files are processed, together with any log file.
 +  * **''-a'' $|$ ''%%--append-backup%%''** Previous output files are concatenated by appending, instead of being kept separate.
 +  * **''%%--directory-backup%%''** Backup files are stored in a single separate subdirectory, named //datafile//''.d'', with subdirectories ''01'', ''02'', $\dots$. ''%%--directory-backup%%'' and ''%%--append-backup%%'' are mutually exclusive, and switching one of them on will force the other to be switched off. ''%%--no-append-backup%%'' ''%%--no-directory-backup%%'' can also be specified with the same effect, except that they do not also imply ''%%--backup%%''.
 +  * **''%%--backup-directory%%'' //dir//** In the case of ''%%--directory-backup%%'', use //// dir as the location of backup files instead of the default.
 +  * **''-s'' $|$ ''%%--nobackup%%''** disables the mechanism whereby an existing output file is saved.
 +  * **''-v'' $|$ ''%%--verbose%%''** causes the procedure to echo debugging information; ''%%--noverbose%%'' selects quiet operation (default).
 +  * **''-k //key//''** where //key// is the licence key. This is normally not necessary since the key should be installed globally when installing Molpro.
 +  * **''-m'' $|$ ''%%--memory%%'' //memory// (in megawords)** specifies the working (stack) memory to be assigned to the program, in 8-byte words. For details, see section [[general program structure#memory allocation|memory allocation]].
 +  * **''-M'' $|$ ''%%--memory-per-node%%'' //M//** total memory per node (stack + GA, in megawords) For details, see section [[general program structure#memory allocation|memory allocation]]
 +  * **''-I'' $|$ ''%%--main-file-repository%%'' //directory//** specifies the directory where the permanent copy of any integral file (file 1) resides. This may be a pathname which is absolute or relative to the current directory (e.g., ’''.''’ would specify the current directory). Normally, the ''-I'' directory should be equal to the ''-d'' working directory to avoid copying of large integral files, since after completion of the job the file will be copied to the directory given after ''-I''. On some main frames, the scratch directory is erased automatically after a job has terminated, and in such cases a different ''-I'' directory, e.g., ''%%$HOME/int%%'', can be specified (environment variables will be expanded at run time). In view of the large integral file sizes, this should be used with care, however. Note that in parallel runs with more than 1 processor the integral file will never be copied, and cannot be restarted.
 +  * **''%%-W %%'' $|$ ''%%--wavefunction-file-repository%%'' //directory//** is similar to ''%%--main-file-repository%%'' except that it refers to the directory for the wavefunction files (2,3 and 4). This determines the destination of permanent wavefunction (dump) files used for storing information like orbitals or CI-vectors etc. These files are essential for restarting a job. As explained for the integral files above, permanent wavefunction files will be copied to //directory// after completion of the job. The default for //directory// is ''%%$HOME/wfu%%''.
 +  * **''%%-X %%'' $|$ ''%%--xml-output%%''** specifies that an additional XML output file suitable for automatic post-processing will be written, with suffix .xml. Important data such as input, geometries, and results are stored in a [[https://www.molpro.net/schema/molpro-output|marked-up format]]. ''%%--no-xml-output%%'' switches off this behaviour.
 +  * **''%%--xml-orbdump%%''** If this option is given, more data such as the basis set and the occupied orbitals are dumped to the XML file.
 +  * **''%%--stdout%%''** Write the plain-text output to standard output instead of the ''.out'' file. The ''.xml'' file is unaffected. This option can be useful when using an integrated development environment.
 +  * **''-L'' $|$ ''%%--library%%'' //directory//** specifies the directory where the basis set library files (''%%LIBMOL*%%'') are found.
 +  * **''-t'' $|$ ''%%--omp-thread-limit%%'' //n//** Specify the maximum number of OpenMP threads, as if the environment variable ''OMP_THREAD_LIMIT'' were set to //n//.
 +  * **''%%--geometry%%''** Use this to obtain an XML output with geometry information, but without performing any electronic structure calculation (e.g. to visualise the geometry). Note that it needs at least one jobstep, e.g. “hf” though this jobstep will not be executed.
 +  * **''%%--no-flush6%%''** Don’t flush the output, this might increase performance on some systems as the expense of being able to poll the output.
 +  * **''-g'' $|$ ''%%--use-logfile%%''** Use a separate logfile for more in-depth output.
 +  * **''%%--nouse-logfile%%''** All output will be in the regular output file.
 +  * **''-E'' $|$ ''%%--exclusive-file-implementation%%''** Specify file implementation. This is mainly for debugging, eg. reproducing non-shared file problems on a system with shared files, normally the default should be used.
 +  * **''%%--name%%'' //name=string//** Set string variable on the command line, eg. ''%%--name%%'' basis=vtz.
 +  * **''-V'' $|$ ''%%--var%%'' //name=value//** Set variable on the command line, eg. ''%%--var%%'' len=1.2.
 +  * **''-k'' $|$ ''%%--licence-token%%''** Specify licence token on the command line.
 +  * **''%%--version%%''** Print Molpro version and exit
 +  * **''%%--database%%''** Instead of executing Molpro, instead run one of the database utility scripts as described in section [[post-processing of output and databases#interrogation and manipulation of databases|interrogation and manipulation of databases]].
 +  * **''%%--sysid%%''** For debugging when the getinfo.sh script does not give the correct sysid.
 +
 +===== Options for launching Molpro =====
 +
 +These options are for the ''molpro'' shell script which is used to launch the ''molpro.exe'' MPI program. These options should be given on the command line or in the ''MOLPRO_OPTIONS'' environment variable as both of these are parsed by the shell script and used to launch ''molpro.exe'', they should not be given in ''.molprorc'' or any other configuration files since these are not read until after ''molpro.exe'' is launched.
 +
 +  * **''-n'' $|$ ''%%--tasks%%'' //tasks/tasks_per_node:smp_threads//** //tasks// specifies the number of parallel processes to be set up.
 +  * **''-N'' $|$ ''%%--task-specification%%'' //user1:node1:tasks1,user2:node2:tasks2$\dots$//** //node1, node2// etc. specify the host names of the nodes on which to run.
 +  * **''-x'' $|$ ''%%--executable%%'' //executable//** specifies an alternative Molpro executable file.
 +
 +===== Options for parallel execution =====
 +
 +The options specific to parallel execution are described [[running_molpro_on_parallel_computers#specifying_parallel_execution | here]].
 +
 +It is very important to read [[running Molpro on parallel computers]] before executing parallel Molpro calculations.
 +
 +===== Tuning Options =====
 +
 +There are a number of other options for tuning and system parameters, but these do not usually concern the general user.
 +
 +Tuning parameters for blas routines (mxma,, mxmb, mxva, mxvb):
 +
 +  * **''%%--tuning-mpplat%%'' //n//** mpp latency in microseconds
 +  * **''%%--tuning-mppspeed%%'' //n//** mpp bandwidth in MB/sec
 +  * **''%%--tuning-flopdgm%%'' //n//** speed of dgemm in MFLOPS
 +  * **''%%--tuning-flopdgv%%'' //n//** speed of dgemv in MFLOPS
 +  * **''%%--tuning-flopmxm%%'' //n//** speed of fortran mxma in MFLOPS
 +  * **''%%--tuning-flopmxv%%'' //n//** speed of fortran mxva in MFLOPS
 +  * **''%%--tuning-mindgv%%'' //n//** use dgemv from mxva/mxvb if matrix dimensions are ge. mindgv
 +  * **''%%--tuning-mindgm%%'' //n//** use dgemm from mxma/mxmb if all matrix dimensions are ge. mindgm
 +  * **''%%--tuning-mindgc%%'' //n//** use dgemm from mxma/mxmb if column dimension is ge. mindgc and other dimensions larger than mindgm2
 +  * **''%%--tuning-mindgr%%'' //n//** use dgemm from mxma/mxmb if row dimension is ge. mindgr and other dimensions larger than mindgm2
 +  * **''%%--tuning-mindgl%%'' //n//** use dgemm from mxma/mxmb if link dimension is ge. mindgl and other dimensions larger than mindgm2
 +  * **''%%--tuning-mindgf%%'' //n//** for old Fujitsu machines, probably obsolete
 +
 +Tuning parameters for fortran versions of mxma/mxmb:
 +
 +  * **''%%--tuning-unroll%%'' //n//** level of unrolling in (2,3, or 4)
 +  * **''-b'' $|$ ''%%--matrix-block-link%%'' $|$ ''%%--tuning-mxmbln%%'' //n//** block dimension for link dimension
 +  * **''-B'' $|$ ''%%--matrix-block%%'' $|$ ''%%--tuning-mxmblk%%'' //n//** block dimension for rows and columns of result matrix
 +  * **''-K'' $|$ ''%%--cache%%'' $|$ ''%%--tuning-cache%%'' //n//** cache size in words. If the total size of the 3 matrices is smaller than this, no blocking.
 +
 +It is not usually necessary to specify any of these options as there are sensible defaults. Sometimes installation dependent options can be found in the system configuration file ''molpro.rc'' in the same directory as the Molpro library files.