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[source]

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)[source]
abstract __post_init__()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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__()[source]
_get_repeated_input_string(indent_lvl)[source]

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)[source]
__delitem__(_Entry__key)[source]
insert(index, value)[source]
__len__()[source]
__str__()[source]

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({'_get_single_input_string', '__post_init__', '__setitem__'}), '_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__()[source]

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)[source]

Return self==value.

_check_unique(meth)[source]

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)[source]

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

_h
_1
class InputParserFreeBlock(_1)[source]

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

_1
class Block[source]

Base class representing an input block for AMS.

_header = ''
__post_init__()[source]

Recursively sets key and block attributes present in self._keyword_dict

property header
static from_def_dict(name, def_dict)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Inserts the block name

Parameters:

indent_lvl (int) – Indentation level

Returns:

Properly indented block name

Return type:

str

_get_block_body(indent_lvl)[source]

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)[source]

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)[source]

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
comment
hidden
unique
gui_name
default
ispath
unit
choices
hiddenchoices
allow_header
ordered
isatomlist
rootdir
engines
extra_info
gui_type
shared_id
default_engine
range
_keyword_dict
_entry_list
_value_changed
class DriverBlock[source]

Represents the highest level block.

_get_block_start(indent_lvl)[source]

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)[source]

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)[source]

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()[source]

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
comment
hidden
unique
gui_name
default
ispath
unit
choices
hiddenchoices
allow_header
ordered
isatomlist
rootdir
engines
extra_info
gui_type
shared_id
default_engine
range
_keyword_dict
_entry_list
_value_changed
class FixedBlock[source]

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

__abstractmethods__ = frozenset({})
__module__ = 'scm.pisa.block'
_abc_impl = <_abc_data object>
_init_finished
comment
hidden
unique
gui_name
default
ispath
unit
choices
hiddenchoices
allow_header
ordered
isatomlist
rootdir
engines
extra_info
gui_type
shared_id
default_engine
range
_keyword_dict
_entry_list
_value_changed
class FreeBlock[source]

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 = ''
__post_init__()[source]

Recursively sets key and block attributes present in self._keyword_dict

_get_block_body(indent_lvl=0)[source]

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)[source]

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[source]

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

_get_block_end(indent_lvl)[source]

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
comment
hidden
unique
gui_name
default
ispath
unit
choices
hiddenchoices
allow_header
ordered
isatomlist
rootdir
engines
extra_info
gui_type
shared_id
default_engine
range
_keyword_dict
_entry_list
_value_changed
class EngineBlock[source]

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

_get_block_start(indent_lvl)[source]

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)[source]

Return EndEngine instead of End

Parameters:

indent_lvl (int) – Indentation level

Returns:

<INDENT>EndEngine

Return type:

str

__getitem__(index)[source]

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)[source]

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)[source]

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
comment
hidden
unique
gui_name
default
ispath
unit
choices
hiddenchoices
allow_header
ordered
isatomlist
rootdir
engines
extra_info
gui_type
shared_id
default_engine
range
_keyword_dict
_entry_list
_value_changed
type_hint(b)[source]

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[source]

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__()[source]

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)[source]
set_to_default()[source]

Reset the key to the default value, if present.

static from_def_dict(name, def_dict)[source]
_get_single_input_string(indent_lvl=0)[source]

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()[source]
__setitem__(index, value)[source]
_update_existing_attr(attr, _Key__name, _Key__value)[source]
__str__()[source]

Return str(self).

_check_for_boolean(val)[source]
_check_for_non_integer_float(val)[source]
__abstractmethods__ = frozenset({'_convert_val'})
__module__ = 'scm.pisa.key'
_abc_impl = <_abc_data object>
_init_finished
comment
hidden
unique
gui_name
default
ispath
unit
choices
hiddenchoices
allow_header
ordered
isatomlist
rootdir
engines
extra_info
gui_type
shared_id
default_engine
range
_keyword_dict
_entry_list
_value_changed
class FloatKey[source]
_convert_val(val)[source]

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)[source]
__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[source]
_convert_val(val)[source]

Accepts anything that can be converted to an integer, except boolean values and floats with a fractional component.

Parameters:

val (int) – value

Returns:

Converted value

Return type:

int

__setitem__(index, value)[source]
__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[source]
_convert_val(val)[source]

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)[source]
__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: Literal = ["Yes", "yes", "No", "no", "True", "true", "False", "false", "t", "f", "T", "F", True, False]
class FloatListKey[source]
_convert_val(val)[source]

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()[source]
__setitem__(index, value)[source]
__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[source]
_convert_val(val)[source]

Accepts any iterable of values that are convertible to integer, except boolean values and floats with a fractional component.

Parameters:

val (Iterable[int]) – value

Returns:

converted value

Return type:

tuple[int, …]

_format_val()[source]
__setitem__(index, value)[source]
__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[source]
__post_init__()[source]

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)[source]

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)[source]
__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[source]
_convert_val(val)[source]

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)[source]
__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[source]
_convert_val(val)[source]

Accepts strings that represent paths.

Parameters:

val (str | Path) – value

Returns:

Converted value

Return type:

str

__setitem__(index, value)[source]
__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)[source]

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)[source]

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
repr_string
type_hint = 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)
__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='')[source]
__init__(name, parent, attributes, doc_str='')[source]

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)[source]

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__()[source]

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)[source]

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)[source]

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)[source]

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.