\(\newcommand{\AA}{\text{Å}}\)

CRYSTALpytools.base.inputbase module

Python wrapper for CRYSTAL inputs. Provides basic classes, methods and attributes to read, operate and write CRYSTAL d12/d3 files.

Structure of classes

1. All the information are stored in the dictionary obj._block_dict, with the keywords as keys and lists as values. See below for definitions of list elements. The sequence of key-value pairs should follow the requirement of d12/d3 files. For example, in Geom, the ‘OPTGEOM’ key-value pair should always be placed after the ‘SUPERCEL’ key-value pair.

2. Keywords in a block are NON-REPEATABLE. If the same keyword can appear multiple times, please consider to divide the input into multiple subblocks. Both Crystal_inputBASE and Properties_inputBASE use ‘dummpy’ subblocks. For details please refer to docs there.

3. Keywords are called as methods. For ‘keyword-like’ keywords (keywords not closed by ‘END’), calling the method (obj.keyword(value)) modifies the value in obj._block_dict. For ‘block-like’ keywords (keyword closed by ‘END’), calling obj.keyword() modifies the sub-block attribute obj._keyword, which is a derivative of BlockBASE. obj.keyword returns to this attribute.

4. For BlockBASE objects, _block_bg attribute has the keyword or title line of a block. For example, Optgeom has ‘OPTGEOMn’ and Geom has title line.

5. Similarly, _block_ed attribute has the ending line of a block. In BasisSet, by default that is ‘ENDBSn’. '' is automatically set for _block_ed if ‘BASISSET’ keyword is used.

6. The _block_data attribute is the formatted CRYSTAL input string, which can be called and updated by the ‘data’ attriute obj.data.

7. _block_key is the sorted, non-repeated lists of keys defined in _block_dict.

8. _block_valid is a boolian to indicate whether to print out the data of this block.

Add keyword-related methods

Layer 1: Crystal_inputBASE or Properties_inputBASE Objects.

Layer 2: All of them are inherited from BlockBASE. For d12, 3 basic blocks, geom, basisSet and scf. For d3, optional, append1 to append5, useful only when the same keyword in main block (not protected by sub-blocks) is set for multiple times, for example, ‘ECHG’ + ‘PATO’ + ‘ECHG’.

Layer 3: Sub-blocks closed by END, such as ‘OPTGEOM’. Inherited from BlockBASE.

Layer 4: Keyword-like inputs or sub-sub-blocks.

• Keywords with ‘matrix-like’ (ndimen*ndimen) inputs, such as ‘SUPERCEL’. Use set_matrix + assign_keyword.

• Keywords with ‘list-like’ (nline + a list of nline, or 1 line of multiple values) inputs, such as ‘ATOMSPIN’. Use set_list + assign_keyword.

• Keywords with 0 or 1 line input, such as ‘TOLDEE’ and ‘CVOLOPT’. Use assign_keyword.

• Other irregular keywords, such as ‘SHRINK’. Design a special scheme and use assign_keyword.

• Sub-sub-blocks, same as sub-blocks. Change _block_bg and _block_ed accordingly.

All the information, including keywords and subblocks, are stored as a dictionary under obj._block_dict attribute. The key is CRYSTAL keyword (not all the keywords are supported). The value is a list.

1. The first element

   • For ‘keyword-like’ keywords None, '' or value(string). None means skipping the keyword and corresponding values. '' prints out keyword. key\nvalue is printed out for other formatted string values.

   • For ‘block-like’ keywords, the first element must not be edited. It is a string that directs to the real attribute of that sub-block, such as _optgeom. Using attribute operation functions and text saved the developer can visit the ‘real’ attribute without triggering potential commands defined in @property decorated keyword(self) functions.

2. The second element: boolian. Whether the keyword requires a block object.

3. The third element: A list of conflicting keywords. See the next section.

4. The fourth element: Valid only if the second element is True. A string that initializes the subblock object. For example, in Geom()._block_dict, the fourth element of the list corresponding to ‘OPTGEOM’ key is ‘crysd12.Optgeom()’. This helps the code to initialize sub-block objects automatically by eval() command. All the sub-blocks are initialized with _block_valid = False when the block object is initialized.

Address conflicts

To address conflicts of keywords, the clean_conflict method is automatically called. A list of conflicting keywords should be given. The list can include the input keyword itself. Conflicting keywords, if they are ‘keyword-like’, the first elements of their ‘value list’ in _block_dict are set to None; if they are ‘block-like’, they are re-initialized with _block_valid = False.

Other comments

1. Not all the keywords in CRYSTAL manual have been implemented. Calling the non-existing attributes or methods causes problems. Please raise an issue in GitHub repo to contact the authors if you need any specific keyword immidiately.

2. Please also read documentations and examples for Crystal_inputBASE, Properties_inputBASE and crystal_io.

Base object of all the input (d12/d3) blocks.

class BlockBASE(bg, ed, dic)

Bases: object

The base class of ‘block’ objects

Parameters:

• bg (str) – Beginning line. Keyword or title

• ed (str) – Ending line.

• dic (dict) – Keyword and value (in text) pairs. Format is listed below.

Returns:

• self (BlockBASE) – New attributes listed below

• self._block_bg (str) – Keyword of the block

• self._block_ed (str) – End of block indicator, ‘END’

• self._block_data (str) – Formatted text string for d12.

• self._block_dict (dict) – Keyword and value (in text) pairs. Key: CRYSTAL keyword in string. Value: A 3*1 or 4*1 list, see below. * 1st element: For keywords: String, formatted output; None, not including the keyword; '', keyword only * 1st element: For subblocks: Name of the ‘real’ attribute (protected by property decorator) * 2nd: bool, whether it is a sub-block or not; * 3rd: A list of conflicting keywords. * 4th: Subblock only. String that initializes the subblock object.

• self._block_key (list) – Allowed keyword list

• self._block_valid (bool) – Whether this block is valid and for print.

property data

Settings in all the attributes are summarized here.

assign_keyword(key, shape, value='')

Transform value into string formats.

Parameters:

• shape (list[int]) – 1D list. Shape of input text. Length: Number of lines; Element: Number of values

• value (list | str) – List, a 1D list of arguments; '' or a list begins with '', return to ''; None or a list begins with None, return None.

Returns:

text (str) – CRYSTAL input

static set_matrix(mx)

Set matrix-like data to get assign_keyword inputs. Used for supercell expansion matrix and strain tensor.

Parameters:

mx (list | str) – ndimen*ndimen list, None, or ''

Returns:

• shape (list) – ndimen*1 1D list. All elements are ndimen.

• value (list) – ndimen*2*1 1D list. Flattened matrix.

static set_list(*args)

Set list-like data to get assign_keyword inputs. Used for lists with known dimensions. Such as atom coordinate list.

Parameters:

*args – '', Clean data; None, Return keyword only; int, list, int for length of the list, list for list data

Returns:

• shape (list) – 1 + length 1D list or []

• args (list) – Flattened list, [] or ‘’

clean_conflict(key)

Addressing the conflictions between keywords.

Parameters:

key (str) – The keyword specified.

update_block()

Update the _block_data attribute: Summarizing all the settings to _block_data attribute for inspection and print

analyze_text(text)

Analyze the input text and return to corresponding attributes