2. API Documentation

Note

As a regular user, you should never need to interact with these classes directly, but only with the autogenerated subclasses present in scm.input_classes.drivers and scm.input_classes.engines. This API reference is meant more for developers wishing to debug or expand/change functionality.

2.1. Entry Module

The Entry class is the abstract base class for all input entries. If provides the skeleton for producing input strings and the mechanics for repeated entries. This class is not meant to be used directly.

class Entry

Abstract base class serving as the base class for the Block and Key classes. Also handles index notation ‘[]’ for repeated blocks and keys by automatically creating new instances of itself upon indexing.

__init__(name=None, comment='', hidden=False, unique=True, gui_name=None, default=None, ispath=False, unit='', choices=None, hiddenchoices=None, header=False, ordered=False, isatomlist=False, rootdir=None, engines=None, extra_info=None, gui_type=None, shared_id=None, default_engine=None, range=None, _keyword_dict=None)

Initialize self. See help(type(self)) for accurate signature.

abstract __post_init__()

Called from the __init__(). This is the method that should be overwritten in subclasses to implement extra behavior. Note that in the autogenerated subclasses, this method is overwritten to define all the instance attributes, so any behavior defined in this method will not be executed in the subclasses that users user to generate AMS input strings with.

__setattr__(_Entry__name, _Entry__value)

Implement setattr(self, name, value).

property value_changed

Property that determines if an entry will be processed by get_input_string(). Will be set to true if the entry was touched in any way. For keys, this means trying to change their values (even if changed to the default value). For blocks, this means any of their keys were touched in any way.

Returns

Whether the value of the entry was changed

Return type

bool

get_input_string(indent_lvl=0)

Generates a valid AMS input string. Note that this method exists for every entry, but generally as user you want to call it on the highest level DriverBlock instance, which will recursively include all its entries.

Parameters

indent_lvl (int, optional) – With how many tabs to indent the string. Useful for dealing with snippets, not with DriverBlock. Defaults to 0.

Returns

Valid AMS input string.

Return type

str

abstract _get_single_input_string(indent_lvl=0)

This method produces the input string for unique Entries. This is the method that needs to be overwritten to implement specific subclasses, not get_input_string().

Parameters

indent_lvl (int, optional) – Indentation level, defaults to 0

Returns

string representing the Entry in the input system.

Return type

str

__getitem__(index)

Using the python index notation [] on a repeated entry (self.unique equal to False), will return a new instance of the same class. This allows you to create a list of entries. The indexing starts at zero and must be sequential, e.g:

block.repeated_entry[0].Temperature = 10
block.repeated_entry[1].Temperature = 20
block.repeated_entry[2].Temperature = 30

Parameters

• self (TEntry) – Typed as a type variable to indicate that the return type is equal to the type of the object you are calling __getitem__ on

• index (int) – Integer index (slicing is not supported). Must be called sequentially, starting at 0.

Raises

IndexError – Raised when called with a non-sequential index, e.g. [2] when [1] was not accessed before.

Returns

Object of the same class as the object you are indexing. Returned object is stored internally as a list and will be present in the final input

Return type

TEntry

__iter__()

_get_repeated_input_string(indent_lvl)

For repeated entries, simply generate a multiline string by repeatedly calling get_input_string() for every entry in self._entry_list

Parameters

indent_lvl (int) – Indentation level

Returns

Multiline string representing all items in the repeated Entry.

Return type

str

abstract __setitem__(index, value)

__delitem__(_Entry__key)

insert(index, value)

__len__()

__str__()

Return str(self).

__abstractmethods__ = frozenset({'__post_init__', '__setitem__', '_get_single_input_string'})

__dict__ = mappingproxy({'__module__': 'scm.pisa.entry', '__doc__': "\n    Abstract base class serving as the base class for the Block and Key classes. Also handles index notation '[]'\n    for repeated blocks and keys by automatically creating new instances of itself upon indexing.\n    ", '__init__': <function Entry.__init__>, '__post_init__': <function Entry.__post_init__>, '__setattr__': <function Entry.__setattr__>, 'value_changed': <property object>, 'get_input_string': <function Entry.get_input_string>, '_get_single_input_string': <function Entry._get_single_input_string>, '__getitem__': <function Entry.__getitem__>, '__iter__': <function Entry.__iter__>, '_get_repeated_input_string': <function Entry._get_repeated_input_string>, '__setitem__': <function Entry.__setitem__>, '__delitem__': <function Entry.__delitem__>, 'insert': <function Entry.insert>, '__len__': <function Entry.__len__>, '__str__': <function Entry.__str__>, '__repr__': <function Entry.__repr__>, '__eq__': <function Entry.__eq__>, '__dict__': <attribute '__dict__' of 'Entry' objects>, '__weakref__': <attribute '__weakref__' of 'Entry' objects>, '__hash__': None, '__abstractmethods__': frozenset({'__setitem__', '__post_init__', '_get_single_input_string'}), '_abc_impl': <_abc_data object>, '__annotations__': {'_init_finished': 'bool', 'comment': 'Final', 'hidden': 'Final', 'unique': 'Final', 'gui_name': 'Final', 'default': 'Final', 'ispath': 'Final', 'unit': 'Final', 'choices': 'Final[list[str] | None]', 'hiddenchoices': 'Final[list[str] | None]', 'allow_header': 'Final', 'ordered': 'Final', 'isatomlist': 'Final', 'rootdir': 'Final', 'engines': 'Final', 'extra_info': 'Final', 'gui_type': 'Final', 'shared_id': 'Final', 'default_engine': 'Final', 'range': 'Final', '_keyword_dict': 'Final', '_entry_list': 'list[Entry]', '_value_changed': 'bool'}})

__hash__ = None

__module__ = 'scm.pisa.entry'

__repr__()

The repr functionality is the core of the source code generation, since it allows the Block and Key classes to generate a string that can be used to construct an instance of themselves. This method decreases verbosity in the repr string by omitting arguments equal to the default values, so the autogenerated code looks a bit cleaner.

Returns

String that can be used to construct an identical instance of the object.

Return type

str

__weakref__

list of weak references to the object (if defined)

_abc_impl = <_abc_data object>

__eq__(_Entry__value)

Return self==value.

_check_unique(meth)

Decorator that is used to wrap any Entry method that is not meant for unique entries (like __getitem__)

Parameters

meth (Callable) – Entry method to decorate

Raises

ValueError – When wrapped method is called on unique instances of the Entry object

Returns

The wrapped method

Return type

Callable

2.2. Block Module

The following classes represent the different types of blocks in the input system. Note that for normal usage, one never needs to instantiate these classes directly. Instead use the autogenerated subclasses present in scm.input_classes.drivers and scm.input_classes.engines.

class InputParserEngineBlock(_h, _1)

Simple container for data created by the InputParser for EngineBlocks. Only used in the Block.from_text() functionality

_h: str

_1: Sequence[str]

class InputParserFreeBlock(_1)

Simple container for data created by the InputParser for FreeBlocks. Only used in the Block.from_text() functionality

_1: Sequence[str]

class Block

Base class representing an input block for AMS.

_header = ''

__post_init__()

Recursively sets key and block attributes present in self._keyword_dict

property header

static from_def_dict(name, def_dict)

Instantiate the relevant Block object from a definition dictionary from the json input definitions. Only used in the autogeneration of scm.input_classes

Parameters

• name (str) – Name of the block to create

• def_dict (dict[str, Any]) – Definition dictionary from the json input definitions.

Returns

The created Block instance

Return type

Block

classmethod from_settings(settings)

Generate a block object from a settings object. Should only be used for backwards compatibility, e.g. old job classes or recipes that will break on receiving a PISA object. Not guaranteed to always work, since it does a to text input and from text input conversion. Examples:

from scm.input_classes import AMS, DFTB
from scm.plams.interfaces.adfsuite.ams import AMSJob
from scm.plams.core.settings import Settings

settings = Settings()
settings.input
settings.input.ams.Task = 'GeometryOptimization'
settings.input.ams.Properties.NormalModes = 'Yes'
settings.input.DFTB.Model = 'SCC-DFTB'

ams = AMS.from_settings(settings)

# this is supported, but fragile:
dftb = DFTB.from_settings(settings)
# this is safer:
ams = AMS.from_settings(settings)
dftb = ams.engine

Parameters

• cls (type[T_Block]) – Block class you want to generate from settings. Usually should be AMS

• settings (Settings) – Settings object to convert from. Should contain ‘input’ attribute.

Raises

ValueError – If settings input does not contain ‘input’ attribute

Returns

Block object with keys and blocks set according to information in settings object.

Return type

T_Block

classmethod from_text(text)

Class method to instantiate a block object from text input. Need to call this on the relevant subclass to work correctly. E.g. for an AMS input string one needs to call AMS.from_text, not Block.from_text

Parameters

• cls (type[T_Block]) – Relevant block class

• text (str) – String representing valid AMS input

Returns

Block object representing the text input

Return type

T_Block

set_from_input_dict(input_dict)

Called from Block.from_text after instantiation of the Block to correctly set the values of the key/block attributes as defined in the text input.

Parameters

input_dict (dict[str, Any]) – dictionary returned by scm.libbase.InputParser

Raises

ValueError – When the text input references an Entry not present in the JSON input definitions, would be caused by faulty text input.

property blocks

Property returning all the blocks in this block

Returns

All the blocks in this block

Return type

tuple[Block, ..]

property keys

Property returning all the keys in this block

Returns

All the keys in this block

Return type

tuple[Key, ..]

property entries

Property returning all the entries (blocks and keys) in this block. Return will be sorted with possible engine blocks at the end.

Returns

Tuple of all entries in this block

Return type

tuple[Entry, ..]

property _lowercase_dict_entry

Lowercase dictionary of all Entries and their lowercase names, used to check if accessed Entry attributes in __setattr__() are an incorrect case variation of an existing attributes.

Returns

Dictionary with lowercase entry names as keys, and entry attributes as values

Return type

dict[str, Entry]

property _dict_entry

Dictionary of all Entries and their names, to find the proper case names of misspelled Entries in __setattr__() .

Returns

Dictionary with entry names as keys, and entry attributes as values

Return type

dict[str, Entry]

__setattr__(_Block__name, _Block__value)

Overrides the default setattribute functionality for multiple added features:

Checking for case mistakes The lookup of attributes is case sensitive, like the python standard, but will provide a helpful error message when you try to do block.temperature = 50 instead of block.Temperature = 50, by providing the user with the proper case name.

Allows overriding of attributes of type ``EngineBlock`` with an ``EngineBlock`` Normally, key and block attributes can not be overridden, since this would break the input system, but for engine blocks this is intended behavior.

Easier syntax for setting key values Allows some_block.some_key = 10 as an alias for some_block.some_key.val = 10

Allows overwriting of ``FreeBlock`` attributes with multiline strings or sequences of strings

Parameters

• __name (str) – Name of instance attribute to set the value of

• __value (Any) – Value to set for th attribute

Raises

Exception – When trying to access a case variation of a key/block attribute

__setitem__(index, value)

Adds support for setting heterogenous repeated blocks (currently only EngineBlock attributes):

driver = HYBRID()
driver.Engine[0] = ADF()
driver.Engine[1] = BAND()

Parameters

• index (int) – Index of the item of the repeated block. Must be used in sequential order, e.g. can’t use [1] before [0] is used.

• value (Block) – Block object for the repeated block.

_get_single_input_string(indent_lvl=0)

A wrapper that concatenates the outputs of self._get_block_start, self._get_block_body, and self._get_block_end. Those are the methods to override in the subclasses.

Parameters

indent_lvl (int, optional) – Indentation level, defaults to 0

Returns

Input string for a unique block.

Return type

str

_get_block_start(indent_lvl)

Inserts the block name

Parameters

indent_lvl (int) – Indentation level

Returns

Properly indented block name

Return type

str

_get_block_body(indent_lvl)

Recursively searches all the key/block attributes build the body by concatenating the outputs of get_input_string for attributes that were changed/touched by the user.

Parameters

indent_lvl (int) – Indentation level

Returns

block body

Return type

str

_get_block_end(indent_lvl)

Simply returns the string end with required indentation.

Parameters

indent_lvl (int) – Indentation level

Returns

End

Return type

str

property value_changed

Recursively searches all Entry attributes to see if any of them has value_changed=True. We consider a key changed if it’s value is changed by the user, even if it is set to the default value. A block is changed when any of its keys or block have their value changed. Used as a condition to include a block in the input string

Returns

Whether the value of this block is different from the default or touched by the user.

Return type

bool

__add__(other)

Implements a soft update of this block with another block via the ‘+’ operator.

Parameters

• self (T_Block) – Left hand object in the addition

• other (T_Block) – Right hand object in the addition

Raises

TypeError – When both blocks are not the same type

Returns

Returns a deepcopy of the lefthand block, where all the attributes that were set in the right hand block, but not in the left hand block, are copied over.

Return type

T_Block

__abstractmethods__ = frozenset({})

__module__ = 'scm.pisa.block'

_abc_impl = <_abc_data object>

_init_finished: bool

comment: Final

hidden: Final

unique: Final

gui_name: Final

default: Final

ispath: Final

unit: Final

choices: Final[list[str] | None]

hiddenchoices: Final[list[str] | None]

allow_header: Final

ordered: Final

isatomlist: Final

rootdir: Final

engines: Final

extra_info: Final

gui_type: Final

shared_id: Final

default_engine: Final

range: Final

_keyword_dict: Final

_entry_list: list[Entry]

_value_changed: bool

class DriverBlock

Represents the highest level block.

_get_block_start(indent_lvl)

Driver blocks don’t have start line or an end line, simply returns an empty string

Parameters

indent_lvl (int) – Indentation level, ignored.

Returns

Empty string

Return type

Literal[“”]

_get_block_end(indent_lvl)

Driver blocks don’t have start line or an end line, simply returns an empty string

Parameters

indent_lvl (int) – Indentation level, ignored.

Returns

Empty string

Return type

Literal[“”]

get_input_string(indent_lvl=- 1)

Generates a valid AMS input string. Note that this method exists for every entry, but generally as user you want to call it on the highest level DriverBlock instance, which will recursively include all its entries.

Parameters

indent_lvl (int, optional) – With how many tabs to indent the string. Useful for dealing with snippets, not with DriverBlock. Defaults to 0.

Returns

Valid AMS input string.

Return type

str

to_settings()

Convert the Block to a PLAMS Settings object. Can be used for Job classes/recipes that don’t support PISA objects. Example:

from scm.input_classes import AMS, DFTB
from scm.plams.interfaces.adfsuite.ams import AMSJob
from scm.plams.core.settings import Settings

ams = AMS()
ams.Task = 'SinglePoint'
ams.Engine = DFTB()

s = Settings()
s.input = ams.to_settings()
AMSJob(settings=s)

This conversion works via serializing to text and using the libbase InputParser to create a settings object from text. Since this is a bit fragile, only recommended to use this method for backwards compatibility.

Returns

Settings object representation of the Block

Return type

Settings

__abstractmethods__ = frozenset({})

__module__ = 'scm.pisa.block'

_abc_impl = <_abc_data object>

_init_finished: bool

comment: Final

hidden: Final

unique: Final

gui_name: Final

default: Final

ispath: Final

unit: Final

choices: Final[list[str] | None]

hiddenchoices: Final[list[str] | None]

allow_header: Final

ordered: Final

isatomlist: Final

rootdir: Final

engines: Final

extra_info: Final

gui_type: Final

shared_id: Final

default_engine: Final

range: Final

_keyword_dict: Final

_entry_list: list[Entry]

_value_changed: bool

class FixedBlock

Standard block with a predefined set of possible keys and blocks.

__abstractmethods__ = frozenset({})

__module__ = 'scm.pisa.block'

_abc_impl = <_abc_data object>

_init_finished: bool

comment: Final

hidden: Final

unique: Final

gui_name: Final

default: Final

ispath: Final

unit: Final

choices: Final[list[str] | None]

hiddenchoices: Final[list[str] | None]

allow_header: Final

ordered: Final

isatomlist: Final

rootdir: Final

engines: Final

extra_info: Final

gui_type: Final

shared_id: Final

default_engine: Final

range: Final

_keyword_dict: Final

_entry_list: list[Entry]

_value_changed: bool

class FreeBlock

A block that can be assigned a multiline string of an iterable of strings, instead of directly assigning attributes. Will simply result in a series of lines in the input text

_multiline_string: str = ''

__post_init__()

Recursively sets key and block attributes present in self._keyword_dict

_get_block_body(indent_lvl=0)

Simply returns an indented version of the multiline string in FreeBlock._multiline_string

Parameters

indent_lvl (int, optional) – Indentation level, defaults to 0

Returns

Indented version of multiline string.

Return type

str

set_from_input_dict(input_dict)

Called from Block.from_text after instantiation of the Block to correctly set the values of the key/block attributes as defined in the text input.

Parameters

input_dict (dict[str, Any]) – dictionary returned by scm.libbase.InputParser

Raises

ValueError – When the text input references an Entry not present in the JSON input definitions, would be caused by faulty text input.

__abstractmethods__ = frozenset({})

__annotations__ = {'_entry_list': 'list[Entry]', '_init_finished': 'bool', '_keyword_dict': 'Final', '_multiline_string': 'str', '_value_changed': 'bool', 'allow_header': 'Final', 'choices': 'Final[list[str] | None]', 'comment': 'Final', 'default': 'Final', 'default_engine': 'Final', 'engines': 'Final', 'extra_info': 'Final', 'gui_name': 'Final', 'gui_type': 'Final', 'hidden': 'Final', 'hiddenchoices': 'Final[list[str] | None]', 'isatomlist': 'Final', 'ispath': 'Final', 'ordered': 'Final', 'range': 'Final', 'rootdir': 'Final', 'shared_id': 'Final', 'unique': 'Final', 'unit': 'Final'}

__module__ = 'scm.pisa.block'

_abc_impl = <_abc_data object>

class InputBlock

Identical to the FreeBlock, but end with EndInput instead of End

_get_block_end(indent_lvl)

Simply returns the string end with required indentation.

Parameters

indent_lvl (int) – Indentation level

Returns

End

Return type

str

__abstractmethods__ = frozenset({})

__module__ = 'scm.pisa.block'

_abc_impl = <_abc_data object>

_init_finished: bool

comment: Final

hidden: Final

unique: Final

gui_name: Final

default: Final

ispath: Final

unit: Final

choices: Final[list[str] | None]

hiddenchoices: Final[list[str] | None]

allow_header: Final

ordered: Final

isatomlist: Final

rootdir: Final

engines: Final

extra_info: Final

gui_type: Final

shared_id: Final

default_engine: Final

range: Final

_keyword_dict: Final

_entry_list: list[Entry]

_value_changed: bool

class EngineBlock

Represents engine blocks. Input string will always start with ‘Engine <engine_name>’ and end with ‘EndEngine’

_get_block_start(indent_lvl)

Prefixes the word Engine to the block start line containing the block name

Parameters

indent_lvl (int) – Indentation level

Returns

<INDENT>Engine <block_name>

Return type

str

_get_block_end(indent_lvl)

Return EndEngine instead of End

Parameters

indent_lvl (int) – Indentation level

Returns

<INDENT>EndEngine

Return type

str

__getitem__(index)

Using the python index notation [] on a repeated entry (self.unique equal to False), will return a new instance of the same class. This allows you to create a list of entries. The indexing starts at zero and must be sequential, e.g:

block.repeated_entry[0].Temperature = 10
block.repeated_entry[1].Temperature = 20
block.repeated_entry[2].Temperature = 30

Parameters

• self (TEntry) – Typed as a type variable to indicate that the return type is equal to the type of the object you are calling __getitem__ on

• index (int) – Integer index (slicing is not supported). Must be called sequentially, starting at 0.

Raises

IndexError – Raised when called with a non-sequential index, e.g. [2] when [1] was not accessed before.

Returns

Object of the same class as the object you are indexing. Returned object is stored internally as a list and will be present in the final input

Return type

TEntry

static _get_engine_class_and_header(header_str)

Only used when generating block objects from text input. Separates the engine name from the possible header and looks it up in scm.input_classes.engine

Parameters

header_str (str) – Line like BAND test_header that started the engine block in the text input

Raises

ValueError – When the corresponding engine class can not be found

Returns

The Engine class and the possible header

Return type

tuple[type[EngineBlock], str | None]

static _from_input_parser(d)

Create an EngineBlock object from the output of the scm.libbase.InputParser

Parameters

d (InputParserEngineBlock) – Dataclass holding the engine block info

Returns

EngineBlock object

Return type

EngineBlock

__abstractmethods__ = frozenset({})

__module__ = 'scm.pisa.block'

_abc_impl = <_abc_data object>

_init_finished: bool

comment: Final

hidden: Final

unique: Final

gui_name: Final

default: Final

ispath: Final

unit: Final

choices: Final[list[str] | None]

hiddenchoices: Final[list[str] | None]

allow_header: Final

ordered: Final

isatomlist: Final

rootdir: Final

engines: Final

extra_info: Final

gui_type: Final

shared_id: Final

default_engine: Final

range: Final

_keyword_dict: Final

_entry_list: list[Entry]

_value_changed: bool

type_hint(b)

Produces the proper type hint for all Block classes. Only necessary for Block classes that are allowed to overwritten as an attribute, such as an EngineBlock or a FreeBlock with a sequence of strings.

Parameters

b (Block) – Block instance to produce type hint for

Returns

Proper type hint.

Return type

str | None

2.3. Key Module

The following classes represent the different types of keys in the input system. Note that for normal usage, one never needs to instantiate these classes directly. Instead, the autogenerated block classes will have key that attributes that are subclasses of the following classes:

class Key

Base class for all key classes in the input system. Keys are single lines in the text input, with the name of the key, followed by a space, and followed by a string representing the value.

__post_init__()

Called from the __init__(). This is the method that should be overwritten in subclasses to implement extra behavior. Note that in the autogenerated subclasses, this method is overwritten to define all the instance attributes, so any behavior defined in this method will not be executed in the subclasses that users user to generate AMS input strings with.

property val

Property representing the key value. Any proposed value will be sent to the abstract method _convert_val(), which is overwritten in each subclass. Values that cannot be converted to the correct type will be rejected.

Parameters

value (Any) – Value to set the key with

abstract _convert_val(value)

set_to_default()

Reset the key to the default value, if present.

static from_def_dict(name, def_dict)

_get_single_input_string(indent_lvl=0)

This method produces the input string for unique Entries. This is the method that needs to be overwritten to implement specific subclasses, not get_input_string().

Parameters

indent_lvl (int, optional) – Indentation level, defaults to 0

Returns

string representing the Entry in the input system.

Return type

str

_format_val()

__setitem__(index, value)

_update_existing_attr(attr, _Key__name, _Key__value)

__str__()

Return str(self).

_check_for_boolean(val)

__abstractmethods__ = frozenset({'_convert_val'})

__module__ = 'scm.pisa.key'

_abc_impl = <_abc_data object>

_init_finished: bool

comment: Final

hidden: Final

unique: Final

gui_name: Final

default: Final

ispath: Final

unit: Final

choices: Final[list[str] | None]

hiddenchoices: Final[list[str] | None]

allow_header: Final

ordered: Final

isatomlist: Final

rootdir: Final

engines: Final

extra_info: Final

gui_type: Final

shared_id: Final

default_engine: Final

range: Final

_keyword_dict: Final

_entry_list: list[Entry]

_value_changed: bool

class FloatKey

_convert_val(val)

Will accept anything that can be converted to a python float, but raises errors on values of type bool, since the type hinter considers them a valid subclass of float, but passing booleans as floats is never intended

Parameters

val (float) – value

Returns

Converted value

Return type

float

__setitem__(index, value)

__abstractmethods__ = frozenset({})

__annotations__ = {'_entry_list': 'list[Entry]', '_init_finished': 'bool', '_keyword_dict': 'Final', '_value_changed': 'bool', 'allow_header': 'Final', 'choices': 'Final[list[str] | None]', 'comment': 'Final', 'default': 'Final', 'default_engine': 'Final', 'engines': 'Final', 'extra_info': 'Final', 'gui_name': 'Final', 'gui_type': 'Final', 'hidden': 'Final', 'hiddenchoices': 'Final[list[str] | None]', 'isatomlist': 'Final', 'ispath': 'Final', 'ordered': 'Final', 'range': 'Final', 'rootdir': 'Final', 'shared_id': 'Final', 'unique': 'Final', 'unit': 'Final', 'val': 'float'}

__module__ = 'scm.pisa.key'

_abc_impl = <_abc_data object>

class IntKey

_convert_val(val)

Accepts anything that can be converted to an integer, except boolean values.

Parameters

val (int) – value

Returns

Converted value

Return type

int

__setitem__(index, value)

__abstractmethods__ = frozenset({})

__annotations__ = {'_entry_list': 'list[Entry]', '_init_finished': 'bool', '_keyword_dict': 'Final', '_value_changed': 'bool', 'allow_header': 'Final', 'choices': 'Final[list[str] | None]', 'comment': 'Final', 'default': 'Final', 'default_engine': 'Final', 'engines': 'Final', 'extra_info': 'Final', 'gui_name': 'Final', 'gui_type': 'Final', 'hidden': 'Final', 'hiddenchoices': 'Final[list[str] | None]', 'isatomlist': 'Final', 'ispath': 'Final', 'ordered': 'Final', 'range': 'Final', 'rootdir': 'Final', 'shared_id': 'Final', 'unique': 'Final', 'unit': 'Final', 'val': 'int'}

__module__ = 'scm.pisa.key'

_abc_impl = <_abc_data object>

class BoolKey

_convert_val(val)

Will accept a set of strings and True or False as boolean values. Will not try to convert to bool, since nearly every python object can be converted to a boolean and passing anything but BoolType rarely on purpose.

Parameters

val (BoolType) – value

Raises

ValueError – When value is not of type BoolType or a case variation of one of the strings

Returns

Converted value

Return type

bool

__setitem__(index, value)

__abstractmethods__ = frozenset({})

__annotations__ = {'_entry_list': 'list[Entry]', '_init_finished': 'bool', '_keyword_dict': 'Final', '_value_changed': 'bool', 'allow_header': 'Final', 'choices': 'Final[list[str] | None]', 'comment': 'Final', 'default': 'Final', 'default_engine': 'Final', 'engines': 'Final', 'extra_info': 'Final', 'gui_name': 'Final', 'gui_type': 'Final', 'hidden': 'Final', 'hiddenchoices': 'Final[list[str] | None]', 'isatomlist': 'Final', 'ispath': 'Final', 'ordered': 'Final', 'range': 'Final', 'rootdir': 'Final', 'shared_id': 'Final', 'unique': 'Final', 'unit': 'Final', 'val': 'bool'}

__module__ = 'scm.pisa.key'

_abc_impl = <_abc_data object>

scm.pisa.key.BoolType: typing.Literal = ["Yes", "yes", "No", "no", "True", "true", "False", "false", "t", "f", "T", "F", True, False]

class FloatListKey

_convert_val(val)

Accepts any iterable of values that are convertible to float, except boolean values.

Parameters

val (Iterable[float]) – value

Returns

converted value

Return type

tuple[float, ..]

_format_val()

__setitem__(index, value)

__abstractmethods__ = frozenset({})

__annotations__ = {'_entry_list': 'list[Entry]', '_init_finished': 'bool', '_keyword_dict': 'Final', '_value_changed': 'bool', 'allow_header': 'Final', 'choices': 'Final[list[str] | None]', 'comment': 'Final', 'default': 'Final', 'default_engine': 'Final', 'engines': 'Final', 'extra_info': 'Final', 'gui_name': 'Final', 'gui_type': 'Final', 'hidden': 'Final', 'hiddenchoices': 'Final[list[str] | None]', 'isatomlist': 'Final', 'ispath': 'Final', 'ordered': 'Final', 'range': 'Final', 'rootdir': 'Final', 'shared_id': 'Final', 'unique': 'Final', 'unit': 'Final', 'val': 'tuple[float, ...]'}

__module__ = 'scm.pisa.key'

_abc_impl = <_abc_data object>

class IntListKey

_convert_val(val)

Accepts any iterable of values that are convertible to integer, except boolean values.

Parameters

val (Iterable[int]) – value

Returns

converted value

Return type

tuple[int, ..]

_format_val()

__setitem__(index, value)

__abstractmethods__ = frozenset({})

__annotations__ = {'_entry_list': 'list[Entry]', '_init_finished': 'bool', '_keyword_dict': 'Final', '_value_changed': 'bool', 'allow_header': 'Final', 'choices': 'Final[list[str] | None]', 'comment': 'Final', 'default': 'Final', 'default_engine': 'Final', 'engines': 'Final', 'extra_info': 'Final', 'gui_name': 'Final', 'gui_type': 'Final', 'hidden': 'Final', 'hiddenchoices': 'Final[list[str] | None]', 'isatomlist': 'Final', 'ispath': 'Final', 'ordered': 'Final', 'range': 'Final', 'rootdir': 'Final', 'shared_id': 'Final', 'unique': 'Final', 'unit': 'Final', 'val': 'tuple[int, ...]'}

__module__ = 'scm.pisa.key'

_abc_impl = <_abc_data object>

class MultipleChoiceKey

__post_init__()

Called from the __init__(). This is the method that should be overwritten in subclasses to implement extra behavior. Note that in the autogenerated subclasses, this method is overwritten to define all the instance attributes, so any behavior defined in this method will not be executed in the subclasses that users user to generate AMS input strings with.

_convert_val(val)

Accepts any strings that is equal to (or a case variation of) the list of strings defined in MultipleChoiceKey.choices.

Parameters

val (str) – value

Raises

ValueError – When val not present in MultipleChoiceKey.choices

Returns

Converted value.

Return type

str

__setitem__(index, value)

__abstractmethods__ = frozenset({})

__annotations__ = {'_entry_list': 'list[Entry]', '_init_finished': 'bool', '_keyword_dict': 'Final', '_value_changed': 'bool', 'allow_header': 'Final', 'choices': 'Final[list[str] | None]', 'comment': 'Final', 'default': 'Final', 'default_engine': 'Final', 'engines': 'Final', 'extra_info': 'Final', 'gui_name': 'Final', 'gui_type': 'Final', 'hidden': 'Final', 'hiddenchoices': 'Final[list[str] | None]', 'isatomlist': 'Final', 'ispath': 'Final', 'ordered': 'Final', 'range': 'Final', 'rootdir': 'Final', 'shared_id': 'Final', 'unique': 'Final', 'unit': 'Final', 'val': 'str'}

__module__ = 'scm.pisa.key'

_abc_impl = <_abc_data object>

class StringKey

_convert_val(val)

Accepts any string. Validates whether the argument passed is actually a string, since calling str(val) would succeed for every possible type of val.

Parameters

val (str) – value

Returns

Converted value

Return type

str

__setitem__(index, value)

__abstractmethods__ = frozenset({})

__annotations__ = {'_entry_list': 'list[Entry]', '_init_finished': 'bool', '_keyword_dict': 'Final', '_value_changed': 'bool', 'allow_header': 'Final', 'choices': 'Final[list[str] | None]', 'comment': 'Final', 'default': 'Final', 'default_engine': 'Final', 'engines': 'Final', 'extra_info': 'Final', 'gui_name': 'Final', 'gui_type': 'Final', 'hidden': 'Final', 'hiddenchoices': 'Final[list[str] | None]', 'isatomlist': 'Final', 'ispath': 'Final', 'ordered': 'Final', 'range': 'Final', 'rootdir': 'Final', 'shared_id': 'Final', 'unique': 'Final', 'unit': 'Final', 'val': 'str'}

__module__ = 'scm.pisa.key'

_abc_impl = <_abc_data object>

class PathStringKey

_convert_val(val)

Accepts strings that represent paths.

Parameters

val (str | Path) – value

Returns

Converted value

Return type

str

__setitem__(index, value)

__abstractmethods__ = frozenset({})

__annotations__ = {'_entry_list': 'list[Entry]', '_init_finished': 'bool', '_keyword_dict': 'Final', '_value_changed': 'bool', 'allow_header': 'Final', 'choices': 'Final[list[str] | None]', 'comment': 'Final', 'default': 'Final', 'default_engine': 'Final', 'engines': 'Final', 'extra_info': 'Final', 'gui_name': 'Final', 'gui_type': 'Final', 'hidden': 'Final', 'hiddenchoices': 'Final[list[str] | None]', 'isatomlist': 'Final', 'ispath': 'Final', 'ordered': 'Final', 'range': 'Final', 'rootdir': 'Final', 'shared_id': 'Final', 'unique': 'Final', 'unit': 'Final', 'val': 'str | Path'}

__module__ = 'scm.pisa.key'

_abc_impl = <_abc_data object>

type_hint(k)

Provides the proper type hint for key attributes for the autogenerated classes. Keys are type hinted as their actual type, plus the type hint of their value to allow for syntax like:

some_block.some_key = 5

to pass the type hinter, instead of the more cumbersome

some_block.some_key.val = 5

Parameters

k (Key) – Key object

Raises

NotImplementedError – When providing a key object for which a type hint is not implemented yet.

Returns

String describing a type hint

Return type

str

2.4. block_subclass_string module

Module that implements writing out of a string that defines a Python subclass of the scm.pisa.block.Block class.

class BlockSubclassAttribute(name, repr_string, type_hint=None)

Simple dataclass describing an attribute to generate valid python code for. name is the under which to store the attribute, repr_string is a string that when interpreted as python code will result in the proper object (Key or Block subclass) and type_hint is the string to be inserted as type hint.

name: str

repr_string: str

type_hint: str | None = None

__annotations__ = {'name': 'str', 'repr_string': 'str', 'type_hint': 'str | None'}

__dataclass_fields__ = {'name': Field(name='name',type='str',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),_field_type=_FIELD), 'repr_string': Field(name='repr_string',type='str',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),_field_type=_FIELD), 'type_hint': Field(name='type_hint',type='str | None',default=None,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),_field_type=_FIELD)}

__dataclass_params__ = _DataclassParams(init=True,repr=True,eq=True,order=False,unsafe_hash=False,frozen=False)

__dict__ = mappingproxy({'__module__': 'scm.pisa.block_subclass_string', '__annotations__': {'name': 'str', 'repr_string': 'str', 'type_hint': 'str | None'}, '__doc__': 'Simple dataclass describing an attribute to generate valid python code for. :attr:`name` is the under which to\n    store the attribute, :attr:`repr_string` is a string that when interpreted as python code will result in the proper\n    object (`Key` or `Block` subclass) and :attr:`type_hint` is the string to be inserted as type hint.\n    ', 'type_hint': None, '__dict__': <attribute '__dict__' of 'BlockSubclassAttribute' objects>, '__weakref__': <attribute '__weakref__' of 'BlockSubclassAttribute' objects>, '__dataclass_params__': _DataclassParams(init=True,repr=True,eq=True,order=False,unsafe_hash=False,frozen=False), '__dataclass_fields__': {'name': Field(name='name',type='str',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),_field_type=_FIELD), 'repr_string': Field(name='repr_string',type='str',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),_field_type=_FIELD), 'type_hint': Field(name='type_hint',type='str | None',default=None,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),_field_type=_FIELD)}, '__init__': <function __create_fn__.<locals>.__init__>, '__repr__': <function __create_fn__.<locals>.__repr__>, '__eq__': <function __create_fn__.<locals>.__eq__>, '__hash__': None})

__eq__(other)

Return self==value.

__hash__ = None

__init__(name, repr_string, type_hint=None)

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'scm.pisa.block_subclass_string'

__repr__()

Return repr(self).

__weakref__

list of weak references to the object (if defined)

class BlockSubclassString(name, parent, attributes, doc_str='')

__init__(name, parent, attributes, doc_str='')

Class that is able to produce valid python code that defines a subclass of scm.pisa.block.Block

Parameters

• name (str) – Name of the class

• parent (Literal[&#39;DriverBlock&#39;, &#39;EngineBlock&#39;, &#39;FreeBlock&#39;, &#39;InputBlock&#39;, &#39;FixedBlock&#39;]) – Parent class to derive from. One of the Block classes

• attributes (Sequence[ClassStringAttribute]) – List of attributes (that represent keys or blocks) to insert in __post_init__() method

• doc_str (str | None, optional) – Class docstring, usually set to _comment metadata of the block, defaults to “”

insert(cls_str)

Insert a class definitions into this class. Nested classes are used to prevent name clashes between different blocks sharing the same name in the AMS universe.

Parameters

cls_str (BlockSubclassString) – Class string to insert.

property lines

All the lines defining this class. Property recursively inserted nested class definitions with the proper indentation.

Returns

List of lines of python code.

Return type

list[str]

__dict__ = mappingproxy({'__module__': 'scm.pisa.block_subclass_string', '__init__': <function BlockSubclassString.__init__>, 'insert': <function BlockSubclassString.insert>, 'lines': <property object>, '__str__': <function BlockSubclassString.__str__>, '__dict__': <attribute '__dict__' of 'BlockSubclassString' objects>, '__weakref__': <attribute '__weakref__' of 'BlockSubclassString' objects>, '__doc__': None, '__annotations__': {'_nested_class_strings': 'list[BlockSubclassString]', '_lines': 'list[str]'}})

__module__ = 'scm.pisa.block_subclass_string'

__str__()

Convert this class to a string of valid python code defining a subclass of scm.pisa.block.Block with the given attributes. Import statements need to added to this string separately

Returns

String of valid python code

Return type

str

__weakref__

list of weak references to the object (if defined)

2.5. Input_def module

Module that implements actually reading in all the json definitions in $AMSBIN/input_def and writes the python source code that represents the blocks to a python module in $AMSBIN/python3.x/* when executed as a script.

block_to_cls_str(block, insert_underscore=True)

Generate a BlockSubclassString object from a Block object. Uses the __repr__ functionality to generate a line of python for every key/block attribute of the Block to convert.

Parameters

• block (input_block.Block) – Block to convert

• insert_underscore (bool, optional) – Whether to prefix the class name with ‘_’. Should be true except for the toplevel block. Used to prevent name clashes between the nested class definition and the instance attribute. Defaults to True

Returns

Class string object that can be used to generate a string containing python code defining the subclass that represents the block.

Return type

BlockSubclassString

write_block_class_to_file(block, path)

Generates python code that defines a specific block and write it to a file. Will insert the necessary imports as well.

Parameters

• block (input_block.Block) – Block object to write to file

• path (Path) – Path to write the file to.

create_input_classes_module(destination_dir, overwrite=False)

Convert all driver and engine block json definitions to python object, and write python code that define these objects to files. Also inserts __init__.py files to turn destination_dir into a python module.

Takes all json files defined in module attributes ENGINE_BLOCK_FILES and DRIVER_BLOCK_FILES as input.

Parameters

• destination_dir (Path) – Folder to write the python module to

• overwrite (bool, optional) – Delete the directory if it already exists, defaults to False

Raises

Exception – When overwrite is set to False, but directory already exists.