How to use the launch script

This page describes the eT_launch script and its options.

What is the launch script

The launch script, eT_launch, is a Python script generated during the configure step. After running setup, it will be located in your build directory. The behaviour of eT_launch does not depend on the location of the script, so you can copy it wherever you want. Note that the testscripts depends on eT_launch being in your build directory, so moving it will make the tests fail. The script uses the argparse Python module, making it easy to provide command line arguments.

The script is invoked with the command

./eT_launch

and, similarly to setup, a list of options can be listed with the --help option.

./eT_launch --help

Note

It is not recommended to run your calculations in build. Add eT_launch to your path in .bashrc and you can run anywhere.

Below is a description of the default behaviour of eT_launch. Almost all of the steps listed can be modified using command line options and/or environment variables.

When running the script, the default behaviour is to create a scratch directory wherever Python feels like. Usually scratch will be something like /tmp/tmp_kyaaapg.

It will then loop over any files with the .inp extension in the calling directory in an unspecified order. Each input file will then be copied to the scratch directory and eT will be executed as a subprocess.

After eT has finished, the output file, the timing file, and any other relevant output files generated by eT will be copied back to the calling directory with a name that depends on the input file. The script will then proceed to the next input file and repeat the process.

Note

After looping over all the input files, the script will delete the scratch directory if all the calculations finished without error messages.

If an error is detected, eT_launch will attempt to copy any generated output files to the calling directory, exit the loop over input files, and raise an exception without deleting scratch.

For example, if my calling directory contains the files ccsd.inp and cc3.inp before calling eT_launch, it should also contain ccsd.out, ccsd.timing.out, cc3.out, and cc3.timing.out afterwards.

All paths given as input or set in environment variables can be given as either absolute or relative to the calling directory.

Warning

If any of the files generated by eT_launch` already exists, they will be overwritten.

Relevant environment variables

This section contains a list of relevant environment variables used by eT_launch. All of them can be overridden by command line options.

eT_SCRATCH

Recommended Specifies where eT_launch should create the scratch directory. For example, if eT_SCRATCH is set to ~/jobs/eT_scratch/, eT_launch will create something like ~/jobs/eT_scratch/tmpfel2lrwd. Overridden by --scratch.

eT_SAVE

eT_launch can save the files generated by eT required for restart, see the -save, --save-restart-dir option below. If this is enabled and eT_SAVE is set, eT_launch will create a directory based on the input file in the directory specified in eT_SAVE. If eT_SAVE is not set, the directory is created in the calling directory. For example, if my input file is ccsd.inp, my eT_SAVE is set to ~/store/eT_save, and my launch command is eT_launch ccsd.inp -save, then ~/store/eT_save/ccsd is created and the restart files are copied there. Overridden by -save, --save-restart-dir if a directory is provided.

LIBINT_DATA_PATH

Specifies the location where eT will look for basis set files. This variable is rarely required to set explicitly because CMake will set the default to the basis set directory shipped with eT. Overrides the default set by CMake and is again overridden by -basis, --basis-path-dir.

The variables below do not affect the behaviour of eT_launch, but may be set for the generated subprocesses depending on the input options.

OMP_NUM_THREADS/MKL_NUM_THREADS

Sets the number of OMP threads available for the eT subprocess.

PYTHONPATH

If PCMSolver is run in the external mode, see -pcm, --pcm-input-file below, the location of PCMSolver will be added to PYTHONPATH for the pcm subprocess.

Input options

Positional argument

input file

The only positional argument of eT_launch and can be placed anywhere, except after optional arguments that take a string such as -save, --save-restart-dir, so it is safest to provide this argument first. It accepts any number of strings with paths to eT input files in the order you wish to execute them. Note that the files don’t need the .inp extension. The order can be important, especially in restart calculations where you want to restart the second from the first. For example, if I want to run a CCSD and CC3 calculation and restart the CC3 calculation from CCSD, I will use eT_launch ccsd.inp cc3.inp. If no input file is explicitly provided, eT_launch will look in the calling directory and use all files with the .inp extension (glob(*.inp)) in whatever order python decides. If no files are found, eT_launch will stop with an error message.

Optional arguments

-h, --help

This is a built in argparse option. Instead of running the script, the list of options and a short description is printed to file.

-v, --verbose

Enables additional printing from eT_launch. Default: False

-of, --output-file

If you want to name your output files something else than the default, you can use this option. The argument must be a number of strings equal to the number of input files. For example,

eT_launch tralala.inp -of trololo.out

will generate the output files trololo.out and trololo.timing.out. Output files do not need to end with the .out extension.

--omp

Specifies the number of OMP threads set for the eT subprocess. See OMP_NUM_THREADS/MKL_NUM_THREADS above.

-nt, --no-timing

Do not copy the timing file from scratch. Useful if you want to reduce spam.

Default: False

--xyz

Copy any .xyz files in scratch to work.

Default: False

--scratch

Specifies exactly which directory to use as scratch. If it does not exist, it will be created.

-ks, --keep-scratch

Tells eT_launch to not delete scratch when finished.

Note

On clusters you may not have permission to delete generated scratch directories. Use this option to avoid spam about lacking permissions in your SLURM.out file or equivalent.

Default: False

i-err, --ignore-errors

With this option, eT_launch will continue to loop over output files, even if errors are detected from eT. It will also delete scratch when finished and exit with nominal status. Mostly for developers.

Default: False

-save, --save-restart-directory

Will make eT_launch create a restart file directory based on the input file and the string provided. If no string is provided, eT_lanch will look for the``eT_SAVE`` environment variable, see eT_SAVE above. If neither a string or eT_SAVE is provided, eT_launch will create a directory in the current work directory. Files that can be used to restart eT will be copied to this directory when eT finishes. The files will be copied if eT finishes with an error message, but if you are running on a cluster and the calculation times out, the files will not be saved.

Warning

This option is useful on clusters where scratch is deleted automatically. However, the size of the restart files can become very large and you will typically have limited space in your home area. Make sure you have set eT_SAVE to a suitable location or provide one explicitly. Filling up your home quota is an excellent way to get an angry email from your system administrator.

-load, --load-restart-directory

Will make eT_launch search for eT restart files in the provided directory and copy them to scratch before starting eT. The number of directories can be as many as there are input files or less. If there are more input files than load directories, restart files will be copied for the first input files. For example, the command

eT_launch ccsd.inp cc3.inp -load ccsd_restart

will look in the ccsd_restart directory for restart files for the first input file, ccsd.inp, but not for the second. If the directory is empty, eT_launch will proceed normally, but it will give an error if the directory does not exist.

-basis, --basis-path-dir

Specifies where eT should look for basis set files through the LIBINT_DATA_PATH environment variable. Default is set by CMake to the basis set directory shipped with eT.

-bd, --binary-dir

Specifies the directory containing the eT executable. Default is set by CMake to the eT build directory.

-pcm, --pcm-input-file

Specifies the PCMSolver input file if PCMSolver should be run separately in external mode.