PISA (Python Input System for AMS)

The input definition classes are a collection of automatically generated Python classes that can be used to created objects that can be serialized into valid text input for the various drivers in the Amsterdam Modelling Suite. It can thus 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 block for all drivers and engines, but it does not provide any way to define a system (use the plams_molecule or unified chemical system for that.)

See here for a description of the AMS input syntax.

It includes 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 autocomplete 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 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, during runtime all values will be validated.

• 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.

Table of contents

• 1. Examples
  • 1.1. Basic Example
  • 1.2. Finding out which keys and blocks are available
  • 1.3. Default values
  • 1.4. Runtime Checks
  • 1.5. Integration with PLAMS
  • 1.6. Repeated blocks and headers
  • 1.7. Free blocks
  • 1.8. Instantiating block instances from existing text input
• 2. API Documentation
  • 2.1. Entry Module
  • 2.2. Block Module
  • 2.3. Key Module
  • 2.4. block_subclass_string module
  • 2.5. Input_def module
• 3. For developers
  • 3.1. Automatic class generation
  • 3.2. Type hinting
• 4. Trouble shooting