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
