Getting Started

This section contains introductory information about installing and running PLAMS.

For quick-start guides on a wider range of topics within PLAMS, see the Examples.

Overview

PLAMS (Python Library for Automating Molecular Simulation) is a flexible and extensible toolkit for streamlining molecular simulation workflows.

It simplifies and automates the process of configuring, running and analyzing computational chemistry calculations. The key features of PLAMS are:

  • Amsterdam Modeling Suite (AMS) Integration: Full support for interacting with AMS programs

  • Parallel Processing: Run jobs in parallel without any need for separate parallelization scripts

  • Scheduler Integration: Integration with job schedulers such as SLURM making large-scale computations easier to manage

  • Automatic File and Folder Organization: PLAMS automatically handles file organization, preventing overwrites and ensuring clean data flows

  • Controllable Re-runs and Restarts: Efficiently manage job executions by preventing redundant runs and easily restarting from crash points if needed

  • Output processing: Extract, post-process, and analyze results, ensuring that only relevant data is used for further calculations or workflows

  • Compatibility with Chemistry Tools: Includes built-in interfaces for popular programs and packages such as ASE, RDKit, Dirac, ORCA, CP2K, DFTB+ and Crystal and more

Quick Start

PLAMS is available to all users of AMS “out of the box” as part of the AMS Python Stack, which can be accessed with the $AMSBIN/amspython command.

For most use-cases, no specific installation outside of AMS is required. For usage outside of amspython, please see the installation guide below.

To get started with PLAMS, import scm.plams into your python script or jupyter notebook. Then, follow one of the examples to help create your script.

For example, the following is based upon Geometry Optimization of Water, and also makes use of PISA, also included in amspython.

# water_opt.py
from scm.plams import from_smiles, AMSJob
from scm.input_classes import drivers, engines

water = from_smiles("O")

driver = drivers.AMS()
driver.Task = "GeometryOptimization"
driver.Properties.NormalModes = "Yes"
driver.Engine = engines.ForceField()
driver.Engine.Type = "UFF"

job = AMSJob(molecule=water, settings=driver, name="water_opt")
results = job.run()

print("Optimized geometry:")
print(results.get_main_molecule())

Running the command $AMSBIN/amspython water_opt.py produces the successful output:

JOB water_opt RUNNING
JOB water_opt FINISHED
JOB water_opt SUCCESSFUL
Optimized geometry:
  Atoms:
    1         O      -0.000360       0.403461       0.000000
    2         H      -0.783821      -0.202431       0.000000
    3         H       0.784180      -0.201030       0.000000
  Bonds:
   (1)--1.0--(2)
   (1)--1.0--(3)

For more advanced workflows including usage of other AMS engines, see the other examples.

Installation Guide

PLAMS and all its required and optional dependencies are included as part of the AMS Python Stack. This is the easiest way to use PLAMS, as it requires no additional installation process.

However, if you want to use PLAMS outside of amspython, since AMS2024.103 PLAMS is available on PyPI and so can be installed via the pip python package installer.

To install the latest version of PLAMS into your python environment, simply run pip install plams. To install a specific version of PLAMS (e.g. 2025.101), run pip install plams==2025.101.

By default, PLAMS only installs a minimal set of required packages on installation using pip. For additional functionality, further optional packages are required. Since AMS2025, these are available for installation through extra dependency groups with pip.

The available groups are:

  • chem: for chemistry packages such as RDKit, ase

  • analysis: for packages used to analyse and plot results of calculations e.g. scipy, matploblib, networkx

  • ams: for technical packages for use with the AMS interface

One or more of these can be installed using the command pip install 'plams[chem,analysis,ams]'.

Users of the AMS will also have to install the scm.amspipe package using the command pip install $AMSHOME/scripting/scm/amspipe.

What’s new in PLAMS for AMS2025?

Added

Changed

  • Calling init() and finish() functions in a script is now optional

  • Functions for optional packages (e.g. RDKit, ASE) are available even when these packages are not installed, but will raise an MissingOptionalPackageError when called

  • get_main_ase_atoms() also includes atomic charges

  • Global config is initialized with ConfigSettings instead of loading from the standard plams_defaults file (see Global settings)

  • status is a JobStatus string enum

  • Supercell and RDKit properties are no longer serialized to AMS input

Fixed

  • charge property on a Molecule is a numeric instead of string type when loading molecule from a file

  • delete_all_bonds() removes the reference molecule from the removed bond instances

  • load() returns the correctly loaded job

  • check() handles a NoneType status, returning False

Deprecated

  • PLAMS launch script is deprecated in favour of simply running with amspython

Removed

  • Legacy BANDJob, DFTBJob, UFFJob, MOPACJob, ReaxFFJob, CSHessianADFJob and ADFJob have been removed. These were deprecated since AMS2019, and replaced by AMSJob.

  • Exception classes AMSPipeDecodeError, AMSPipeError, AMSPipeInvalidArgumentError, AMSPipeLogicError, AMSPipeRuntimeError, AMSPipeUnknownArgumentError, AMSPipeUnknownMethodError, AMSPipeUnknownVersionError, were moved from scm.plams to scm.amspipe.

What’s new in PLAMS for AMS2024?

  • Packmol interface has been extended to pack in crystal voids and to get the total system charge from the sum of the constituent molecules

  • Additions to AMSResults: get_normal_modes(), get_polarizability(), get_ir_spectrum(), get_ir_spectrum_md(), get_frequency_spectrum(), get_force_constants()

  • Additions to Molecule: get_moments_of_inertia(), get_gyration_radius(), align2mol()

What’s new in PLAMS for AMS2023?