2. Getting started¶
This section contains general information about installing and running PLAMS.
2.1. 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 subfolders:
src for source files of all the modules,
bin for executable scripts and
doc for the source of this documentation. The source of the package is divided into subpackages:
core: all the essential modules defining the skeleton of the library
interfaces: modules with interfaces to external binaries
tools: modules with small utilities like periodic table, file readers etc.
plams_defaults: a separate file defining all the adjustable options (see below for details)
Another imporant part of PLAMS is the executable script used for running or restarting your workflows. It is called simply
plams and it’s located in the
bin folder. We refer to it as the master script. Further in this section you can find the dedicated chapter explaining the usage of the master script.
2.2. Installing PLAMS¶
You can install PLAMS on your computer using one of the following ways:
- If you are using ADFSuite, PLAMS is already intalled there (
$ADFHOME/scripting/plams) and configured to work with a built-in Python coming with ADFSuite (you can access it with
startpythoncommand). The master script is added to
$ADFBIN, so it should be directly visible from your command line.
- The latest PLAMS stable release can be installed directly from PyPi by typing
pip install plamsin your command line. The master scipt will be installed along other global system executables (platform dependent) and should be visible from your command line.
- Any current or historic version can be downloaded or cloned from PLAMS github page. The
releasebranch points to the latests stable release, while the
masterbranch is the most recent development snapshot. Please don’t forget to adjust your environment: add the
srcsubfolder to your
You can combine methods 2 and 3 and fetch PLAMS from GitHub using
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 and dill (enhanced pickling).
When you install PLAMS using
pip, these packages will be installed automatically. If you use ADFSuite, they are already there. In any other case you can install them with
pip install [package name].
Inside your Python interpreter or in Python scripts PLAMS is visible as a subpackage of the
scm package, so you can import it with:
from scm.plams import *
All PLAMS modules are then imported and all useful identifiers are added to the main namespace.
Usually in Python
import * is considered a bad practice and discouraged. However, PLAMS internally takes care of namespace cleanliness and imports only necessary things with
import *. Importing with
import * allows you to use identifiers like
BANDJob instead of
scm.plams.BANDJob which makes your scripts shorter and more readable. Throughout this documentation it is assumed that
import * is used so identifiers are not prefixed with
scm.plams. in any example. If, for some reason, you don’t like it, feel free to use
import scm.plams or
from scm import plams.
2.3. Running PLAMS¶
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 has to be executed from the command line with
python [filename] (
startpython [filename] in case of ADFSuite Python). Keeping these restrictions in mind can be a bit inconvenient, so PLAMS comes with an executable script called master script that takes care of the proper initialization and exit. See Master script for details.
Of course PLAMS can be also run interactively using Python interpreter. 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.
2.4. Defaults file¶
The defaults file is called
plams_defaults and it is located in
src/scm/plams. 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
init() to see 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 read this file to have an overview of what and how can be tweaked (it’s not long, I 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 further PLAMS runs. To tweak a particular setting just for a single script, it is better do introduce this change at inside the script itself. This is done by copying corresponding lines from the defaults file at the top of your script, for example:
config.log.stdout = 1 config.job.pickle = False config.default_jobrunner = JobRunner(parallel=True, maxjobs=8)
2.5. Master script¶
The master script is an executable file called simply
plams located in the
bin subfolder. 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 master script takes care of all the important things mentioned earlier in this chapter, like 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 master script:
from scm.plams import * init() # ========= # actual script here # ... # ========= finish()
python [filename] (or
With the master script:
# ========= # actual script here # ... # =========
Besides that, the master script offers several convenient command line arguments allowing you to tune the behavior of your script without a need to edit the script itself.
2.5.1. Working folder location¶
The master script allows you to pick custom name and location for the main working folder. The main working folder is an initially empty folder that is created on
init(). All files produced by PLAMS and other programs executed by it are saved in the main working folder (usually in some of its subfolders). Each separate run of PLAMS has its separate main working folder.
By default the main working folder is located in the directory where your script was executed and is called
plams.xxxxx where xxxxx is the PID of the Python process. You can change this behavior by supplying
--folder) arguments to the master script to choose, respectively, the location and the name of the main working folder. For example the command:
plams -p /home/user/science -f polymers myscript.plms
/home/user/science/polymers as the main working folder regardless where this command was executed.
It is strongly recommended to perform each PLAMS run in a fresh, empty folder (i.e. supplying a non-existing folder name and letting PLAMS automatically create it). Using an existing folder is possible for various compatibility reasons with other tools, but can lead to unpredictable behavior if the folder was not empty.
2.5.2. Passing variables¶
With the master script you can also pass variables to your script directly from the command line. This can be done with
--var) parameter that follows the syntax
-v variable=value (mind the lack of spaces around equal sign, it is a must). For a script executed that way, there is an additional global string variable with the name
variable and the value
'value' visible in the script’s namespace. For example if the script in file
script1.plms looks like this:
print('Chosen basis: ' + basis) print('Number of points: ' + n) print(type(n)) # do something depending on n and basis
and you execute it with:
plams -v n=10 -v basis=DZP script1.plms
the standard output will be:
Chosen basis: DZP Number of points: 10 str # [output of "do something"]
Three important things to keep in mind about
- no spaces around equal sign,
- each variable requires separate
- the type of the variable is always string (like in the example above). If you want to pass some numerical values make sure to convert them from strings to numbers inside your script.
2.5.3. Importing past jobs¶
You can instruct the master script to load the results of some previously run jobs by supplying the path to the main working folder of a finished PLAMS run with
--load) parameter. To find out why this could be useful, please see Pickling and Rerun prevention.
This mechanism is equivalent to using
load_all() function at the beginning of your script. That means executing your script with
plams -l /some/path myscript.plms works just like putting
load_all(/some/path) at the beginning of
myscript.plms and running it with
plams myscript.plms. The only difference is that, when using
load_all() inside the script, you can access each of the loaded jobs separately by using the dictionary returned by
load_all(). This is not possible with
-l parameter, but all the loaded jobs will be visible to Rerun prevention.
Multiple different folders can be supplied with
-l parameter, but each of them requires a separate
plams -l /some/path -l /other/path myscript.plms
2.5.4. Restarting failed script¶
The master script can be called with an additional argumentless
-r parameter (or
--restart). That way the master script is executed in “restart mode”. The restart mode requires specifying
-f flag and it has to point to an existing folder (otherwise
-r flag is ignored).
In the restart mode PLAMS will import all the successful jobs from the given folder and then use the same folder for the current run. For example, after:
$ plams myscript.plms [17:28:40] PLAMS working folder: /home/user/plams.12345 #[some successful work] [17:56:22] Execution interrupted by the following exception: #[exception details]
you can edit
myscript.plms, remove the cause of crash and restart your script with:
$ plams -r -f plams.12345 myscript.plms
(the above command needs to be executed in
/home/user. Otherwise, you need to add
-p /home/user to tell the master script where to look for
2.5.5. Multiple input scripts¶
The master script can be called with more than one positional argument, like for example:
plams script1.plms script2.plms script3.plms
All the files supplied that way are concatenated into one script and then executed (that means things declared in script1 are visible in script2 and script3). Using this feature for completely unrelated scripts is probably not a good idea, but it can be useful for example when first files contain just definitions of your own functions, derived classes, settings tweaks etc. that are then used in the last file:
plams config/debug_run.plms settings/adf/adf_fde.plms actual_script.plms
That way you can build your own library of reusable code snippets for tasks that are most frequently occurring in your daily work, customize PLAMS according to your personal preferences and make your working environment truly modular.
By the way, your scripts do not need to have
.plms file extension, it is just a convention. They can be any text files.