Getting started¶

Library contents¶

PLAMS comes in a form of Python 3 package (earlier versions were also compatible with Python 2, but as Python 3 becomes more and more popular, we decided to drop Python 2 compatibility). The root folder of the package contains the following:

• core: core subpackage containing all the essential modules defining the skeleton of the library
• interfaces: subpackage with interfaces to external binaries
• tools: subpackage with small utilities like unit converter, periodic table, file readers etc.
• recipes: subpackage with examples of simple job types built on top basic PLAMS elements
• doc: Sphinx source of this documentation
• scripts: folder with executable scripts
• plams_defaults: a separate file defining all the adjustable options accessible via config object (see below for details)

An imporant part of PLAMS worth mentioning here is the executable script used for running or restarting your workflows. It is called simply plams and it’s located in the scripts folder. We will refer to it as the launch script or simply launcher. Further in this section you can find the dedicated chapter explaining the usage of the launch script.

Installing PLAMS¶

You can install PLAMS on your computer using one of the following ways:

1. If you are using Amsterdam Modeling Suite, PLAMS is shipped as a part of scm Python package ($AMSHOME/scripting/scm/plams) and configured to work with a built-in Python coming with AMSuite (you can access it with amspython command). The launch script is added to $AMSBIN, so it should be directly visible from your command line (as long as $AMSBIN is in your $PATH).
2. The latest PLAMS stable release can be installed directly from PyPi by typing pip install plams in your command line. The launch scipt will be installed along other global system executables (platform dependent) and should be visible from your command line.
3. Any current or historic version can be downloaded or cloned from PLAMS GitHub page. The release branch points to the latests stable release, while the master branch is the most recent development snapshot.
4. You can combine methods 2 and 3 and fetch PLAMS from GitHub using pip: pip install git+https://github.com/SCM-NV/PLAMS.git@master (make sure to have Git installed and to choose the proper branch)

PLAMS requires the following Python packages as dependencies:

• numpy
• dill (enhanced pickling)
• ase (optional dependency)
• rdkit (optional dependency)

If you are using Amsterdam Modeling Suite, all the above packages are already included in our Python stack. When you install PLAMS using pip, the required packages (numpy and dill)will be installed automatically. For optional dependencies, or in any other case you can install them with pip install [package name].

Updating PLAMS¶

PLAMS is still a relatively new project and new developments based on users’ feedback are added frequently. Because of that some users might prefer to use the recent development version (master branch on GitHub) rather than the usual stable release (release branch).

If you’re running PLAMS as a part of Amsterdam Modeling Suite you can update the library to the recent development snapshot simply by downloading a ZIP archive from PLAMS GitHub page and replacing contents of $AMSHOME/scripting/scm/plams with the contents of that archive.

If you obtained PLAMS using Git or pip please use the usual Git or pip methods to pull a new version (git pull or pip install --upgrade plams)

Running PLAMS¶

Inside your Python interpreter or in Python scripts PLAMS is visible as a subpackage of the scm package, so you can import it with one of the following commands:

import scm.plams
from scm import plams
from scm.plams import *

A PLAMS script is in fact a general Python script that makes use of classes and functions defined in the PLAMS library. To work properly such a script has to follow two simple restrictions. At the very beginning of the script one must initialize PLAMS environment by calling public function init(). Without this initialization almost every PLAMS function or class call results in a crash. Similarly, at the end of the script public function finish() needs to be called to properly clean the main working folder and ensure proper closure of parallel scripts. You can find more detailed information about these two functions in Public functions section.

To sum up, a proper PLAMS script needs to look like this:

from scm.plams import *
init()
# =========
# actual script here
# ...
# =========
finish()

and it should be executed from the command line with python [filename] (amspython [filename] in case of AMS Python stack). Keeping these restrictions in mind can be a bit inconvenient, so PLAMS comes with the launcher that takes care of the proper initialization and cleaning. See The launch script for details.

Of course PLAMS can be also run interactively. After starting your favorite Python interpreter you need to manually import and initialize the environment with from scm.plams import * and init(). Then you can interactively run any Python command relying on PLAMS. If you run any jobs in the interactive mode make sure to use finish() before closing the interpreter to ensure that all the jobs are gently finished and the main working folder is cleaned.

Defaults file¶

The defaults file is called plams_defaults and it is located in the root folder of the package. If you installed PLAMS using pip, the defaults file could be a bit difficult to find (usually somewhere in site-packages subfolder of your Python). If you can’t find it, just get a fresh copy from GitHub, put it somewhere on your disk and set $PLAMSDEFAULTS environmental variable pointing to it. See also init() to find how PLAMS looks for the defaults file.

The defaults file contains a list of commands that adjust various aspects of PLAMS behavior. The file is self-explanatory: each command is preceded with a comment explaining what it does. We strongly recommend to have a quick glance at that file. It gives an overview of what and how can be tweaked (it’s not long, we promise).

If you wish to globally change some setting you can do it by modifying the defaults file. Changes you make there are going to affect all future PLAMS runs. To tweak a particular setting just for a single script, copy a corresponding line from the defaults file and place it at the top of your script. For example:

config.log.stdout = 1
config.job.pickle = False
config.default_jobrunner = JobRunner(parallel=True, maxjobs=8)

The launch script¶

The launch script is an executable file called simply plams located in the scripts folder. If your $PATH variable is configured properly, you can type in your command line plams -h or plams --help for a short help message.

The launch script provides a convenient way of executing PLAMS scripts and takes care of important things mentioned earlier in this chapter: properly importing and initializing PLAMS and cleaning after all the work is done. Thanks to that your actual script does not need to contain import, init or finish commands.

Without the launcher:

from scm.plams import *
init()
# =========
# actual script here
# ...
# =========
finish()

executed with python [filename] (or amspython [filename]).

With the launcher:

# =========
# actual script here
# ...
# =========

executed with plams [filename].

Besides that, the launch script offers several command line arguments allowing you to tune the behavior of your script without a need to edit the script itself.

plams -p /home/user/science -f polymers myscript.plms

print('Chosen basis: ' + basis)
print('Number of points: ' + n)
print(type(n))
# do something depending on n and basis

plams -v n=10 -v basis=DZP script1.plms

Chosen basis: DZP
Number of points: 10
str
[rest of the output]

plams -l /some/path -l /other/path myscript.plms

$ plams -f stuff myscript.plms
[17:28:40] PLAMS working folder: /home/user/stuff
# [some successful work]
[17:56:22] Execution interrupted by the following exception:
# [exception details]

$ plams -f stuff -r myscript.plms
RESTART: Moving stuff to stuff.res and restarting from it
[18:03:34] PLAMS working folder: /home/user/stuff

$ plams myscript.plms
[17:28:40] PLAMS working folder: /home/user/plams_workdir
# [some successful work]
[17:56:22] Execution interrupted by the following exception:
# [exception details]

[...debug the script...]

$ plams -r myscript.plms
RESTART: Moving plams_workdir to plams_workdir.res and restarting from it
[18:03:34] PLAMS working folder: /home/user/plams_workdir

plams script1.plms script2.plms script3.plms

plams config/debug_run.plms settings/adf/adf_fde.plms actual_script.plms