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 analyze 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
.
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 AMS2025?¶
Added¶
Support for AMS ChemicalSystem within
AMSJob
andAMSResults
.AMSJob
can accept aChemicalSystem
as an input system, and the methodsget_system()
,get_input_system()
andget_main_system()
onAMSResults
return aChemicalSystem
. These provide the option to use aChemicalSystem
in place of a PLAMSMolecule
.Support for work functions through
get_work_function_results()
andplot_work_function()
Interface to the Serenity program through classes such as
SerenityJob
,SerenitySettings
, andSerenityResults
.Improved job logging. The method
get_errormsg()
is enforced on theJob
base class and job errors now appear in the PLAMS output. In addition a summary csv logfilejob_logfile.csv
is created in the main directory with details about job timings and status.- Improved
Settings
access, comparison and manipulation, with additional methods:
- Improved
JobAnalysis
tool for easy extraction and comparison of job data, including statuses, settings and resultsAMSViscosityFromBinLogJob
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 boxplot_grid_molecules()
for plotting multiple molecules with rdkitplot_phonons_band_structure()
,plot_phonons_dos()
andplot_phonons_thermodynamic_properties()
for creating phonon plotsdelete_atoms()
for deleting multiple atoms with partial success
Changed¶
Calling
init()
andfinish()
functions in a script is now optionalExceptions raised in
prerun()
andpostrun()
will always be caught and populate error messageFunctions for optional packages (e.g.
RDKit
,ASE
) are available even when these packages are not installed, but will raise anMissingOptionalPackageError
when calledGlobal
config
is initialized withConfigSettings
instead of loading from the standardplams_defaults
file (see Global settings)get_main_ase_atoms()
also includes atomic chargesstatus
is aJobStatus
string enumMake
Job
class inherit fromABC
and mark abstract methods
Fixed¶
- In
Molecule
: delete_all_bonds()
removes the reference molecule from the removed bond instancesadd_hatoms()
to use bonding information if available when adding new hydrogen atomscharge
property on aMolecule
is a numeric instead of string type when loading molecule from a file
- In
Deprecated¶
PLAMS launch script is deprecated in favour of simply running with
amspython
Removed¶
Legacy
BANDJob
,DFTBJob
,UFFJob
,MOPACJob
,ReaxFFJob
,CSHessianADFJob
andADFJob
have been removed. These were deprecated since AMS2019, and replaced byAMSJob
.Exception classes
AMSPipeDecodeError
,AMSPipeError
,AMSPipeInvalidArgumentError
,AMSPipeLogicError
,AMSPipeRuntimeError
,AMSPipeUnknownArgumentError
,AMSPipeUnknownMethodError
,AMSPipeUnknownVersionError
, were moved fromscm.plams
toscm.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: AMSCalculator: ASE geometry optimizer with AMS forces)
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. 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
A class for generating and analyzing conformers
Quick jobs, like for example the
preoptimize()
function let you quickly optimize a MoleculePackmol 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 Examples