1. Introduction
***************

The input classes package ("scm.input_classes") contains a collection
of automatically generated Python classes that can be used to create
objects that can be serialized into valid text input for the various
drivers in the Amsterdam Modeling Suite. It can therefore be used as
an alternative for the settings object normally located under
"settings.input" used to create an "AMSJob" instance. It contains
support for all the keys and blocks for all drivers and engines, but
it does not provide any way to define a system (use
"scm.plams.Molecule" or "scm.base.ChemicalSystem" for that). See here
for a description of the AMS input syntax.

The input classes package is generated by, and depends on, the package
PISA (*Python Input System for AMS*, "scm.pisa"). Whilst this contains
the base classes which the input classes are built on, as a user, you
should only need to interact directly with "scm.input_classes".

Using these input classes brings the following features:

* **Autocompletion**: In any editor that supports autocompletion for
  Python objects (such as VSCode, PyCharm, JupyterLab, etc.), you will
  be able to tab-complete block and key names.

* **Type hinting**: If you are using any type-checking linting in your
  editor (such as MyPy or Pyright/Pylance), it will provide warnings
  when assigning values with the wrong type (such as a string for an
  integer key or an invalid choice for a multiple choice key). VSCode
  will even autocomplete the various options for multiple choice keys.

* **Runtime validation**: For any checks not possible in the type
  hinting system, or for users who don't use static type analysis in
  their editor, all values will be validated at runtime.

* **Serialization**: The Python objects can be serialized into valid
  text input for the various AMS drivers and also be constructed from
  valid AMS text input, allowing for programmatic editing of existing
  input files.

* **PLAMS integration**: A driver object can be placed inside of a
  settings object at "settings.input", which can be passed to an
  "AMSJob" instance.

* Complete support for all features of the PLAMS input system, such as
  repeated blocks, free blocks, and headers.

These features all work together to try and prevent common mistakes
made when creating input either by hand or using the "Settings" class,
such as:

* Inserting non-existing keys or blocks.

* Accidentally inserting an attribute into a settings object by trying
  to access it.

* Setting key values of an invalid type.

* Using invalid options for multiple choice keys.

* Not specifying which engine to use

Besides preventing mistakes, it also aims to provide a more Pythonic
and less magical syntax for the more advanced input features.
