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 Python Examples collection.

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 Python Examples to help create your script.

For example, the following is based upon the water optimization example.

# water_opt.py
from scm.plams import from_smiles, Settings, AMSJob

water = from_smiles("O")

settings = Settings()
settings.input.ams.Task = "GeometryOptimization"
settings.input.ams.Properties.NormalModes = "Yes"
settings.input.ForceField.Type = "UFF"

job = AMSJob(molecule=water, settings=settings, 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 Python 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, extra 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 analyze and plot results of calculations, e.g. scipy, matplotlib, 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 AMS will also have to install the scm.amspipe package using the command pip install $AMSHOME/scripting/scm/amspipe.

A final option is to download PLAMS directly from the GitHub page. Released versions are available since AMS2024.103. The latest (unreleased) development version can be downloaded from the trunk branch. Once the downloaded zip file has been extracted, navigate to its location and run pip install . to install into your Python environment.

What’s new in PLAMS for AMS2026?

Added

• Improved molecular visualization. The view() function allows visualization of molecules and chemical systems using AMSView, which can be easily rendered in a Jupyter notebook or saved as images.

• Improvements to the JobAnalysis tool for collecting and analyzing job results, with additional methods:

  • add_rkf_field() to simplify adding values from an RKF file to the analysis

  • get_settings_field_key() and get_rkf_field_key() methods to simplify getting the keys for analysis fields

• Additional functionality to assist with workflows:

  • jobs_in_directory() context manager to allow jobs to run in a subdirectory of the PLAMS working directory

  • delete() and rename() methods for deleting/renaming job files and directories

  • on_status_change() callback, available on global config, which fires any time a job status is updated and allows notifications when jobs finish or error

  • config_context() context manager and get_config() function allow context-based override of global config settings

• Additional methods to get results from AMS calculations:

  • get_pvdos() method to get partial vibrational spectra

  • get_main_engine_name()

  • get_reduced_masses()

• Dedicated job for Energy Decomposition Analysis in BAND BANDFragmentJob

• Method balance() to find a balanced ReactionEquation

• Many type hints added across the code to aid scripting through an IDE

Changed

• AMSAnalysisJob has PISA support, accepts multiple AMSJob instances as input, and no longer overwrites user-supplied input settings

• get_normal_modes() explicitly gives the option to return mass-weighted Hessian eigenvectors

• JobAnalysis returns an updated copy on modification instead of performing operations in-place

• packmol() function made more flexible, now accepting a single None value for n_molecules if two of n_atoms, density and box_bounds are specified (the missing value is then auto-calculated)

Fixed

• Method to guess density in packmol_around() changed to resolve large underestimations in molecular volumes

Deprecated

• add_to_class() decorator is deprecated in favor of using standalone functions or subclasses

What’s new in PLAMS for AMS2025?

Added

• Support for AMS ChemicalSystem within AMSJob and AMSResults. AMSJob can accept a ChemicalSystem as an input system, and the methods get_system(), get_input_system() and get_main_system() on AMSResults return a ChemicalSystem. These provide the option to use a ChemicalSystem in place of a PLAMS Molecule.

• Support for work functions through get_work_function_results() and plot_work_function()

• Interface to the Serenity program through classes such as SerenityJob, SerenitySettings, and SerenityResults.

• Improved job logging. The method get_errormsg() is enforced on the Job base class and job errors now appear in the PLAMS output. In addition, a summary CSV logfile job_logfile.csv is created in the main directory with details about job timings and status.

• Improved Settings access, comparison and manipulation, with additional methods:

  • nested_keys()

  • block_keys()

  • contains_nested()

  • pop_nested()

  • compare()

  • remove()

  • difference()

• JobAnalysis tool for easy extraction and comparison of job data, including statuses, settings and results

• AMSViscosityFromBinLogJob for running the AMS trajectory analysis tool to extract viscosity

• Additional methods:

  • packmol_around() to pack around an existing molecule or pack molecules into a non-orthorhombic box

  • plot_grid_molecules() for plotting multiple molecules with rdkit

  • plot_phonons_band_structure(), plot_phonons_dos() and plot_phonons_thermodynamic_properties() for creating phonon plots

  • delete_atoms() for deleting multiple atoms with partial success

Changed

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

• Exceptions raised in prerun() and postrun() will always be caught and populate the error message

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

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

• get_main_ase_atoms() also includes atomic charges

• status is a JobStatus string enum

• Make Job class inherit from ABC and mark abstract methods

Fixed

• In Molecule:

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

  • add_hatoms() to use bonding information if available when adding new hydrogen atoms

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

• In Job classes:

  • load() returns the correctly loaded job

  • run() locking issues resolved for multijobs when errors raised within prerun() and postrun() methods

  • check() handles a NoneType status, returning False

Deprecated

• PLAMS launch script is deprecated in favor 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.

For a fine-grained changelog including technical details, see the GitHub changelog.

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?

• The ASE Calculator for AMS class for running any AMS engine with ASE (see: ASE calculator)

• Classes for calculating reduction and oxidation potentials with ADF and optionally COSMO-RS

• The ADFCOSMORSCompoundJob class for running jobs equivalent to “Task COSMO-RS Compound” in the AMS GUI (see: COSMO-RS compound example). Such a job generates a .coskf file for use with COSMO-RS.

• The calculation of the vibronic density of states has been added to PLAMS.

• Classes for running and restarting molecular dynamics (MD) jobs with AMS (see: Molecular dynamics with Python)

• A class for generating and analyzing conformers

• Quick jobs, like for example the preoptimize() function let you quickly optimize a Molecule

• Packmol interface for generating liquid and gas mixtures, solid-liquid interfaces, and microsolvation spheres

• File format conversion tools for converting VASP, Gaussian, or Quantum ESPRESSO output to ams.rkf and engine.rkf files that can be opened with the AMS GUI

• Plotting tools for plotting a molecule or ASE Atoms inside a Jupyter notebook

• Plotting tools for plotting the electronic band structure

• Additions to AMSResults: get_homo_energies(), get_lumo_energies, get_smallest_homo_lumo_gap()

• Additions to Molecule: guess_atomic_charges(), set_density(), get_unique_bonds(), get_unique_angles()

• Many new Python Examples