FOX.io.read_prm¶

An abstract container for reading and writing files.

Index¶

PRMContainer([filename, atoms, bonds, …]) A container for managing prm files.

API¶

class FOX.io.read_prm.PRMContainer(filename=None, atoms=None, bonds=None, angles=None, dihedrals=None, improper=None, impropers=None, nonbonded=None, nonbonded_header=None, nbfix=None, hbond=None)[source]¶

A container for managing prm files.

pd_printoptions¶

A dictionary with Pandas print options. See Options and settings.

Type:	`dict` [`str`, `object`], private

CP2K_TO_PRM¶

A mapping providing tools for converting CP2K settings to .prm-compatible values. See CP2K_TO_PRM.

Type:	`Mapping` [`str`, `PRMMapping`]

_PRIVATE_ATTR: ClassVar[FrozenSet[str]] = frozenset({'_pd_printoptions'})¶: A frozenset with the names of private instance attributes. These attributes will be excluded whenever calling PRMContainer.as_dict().

HEADERS: Tuple[str, …] = ('ATOMS', 'BONDS', 'ANGLES', 'DIHEDRALS', 'NBFIX', 'HBOND', 'NONBONDED', 'IMPROPER', 'IMPROPERS', 'END')¶: A tuple of supported .psf headers.

INDEX: Mapping[str, List[int]] = mappingproxy({'atoms': [2], 'bonds': [0, 1], 'angles': [0, 1, 2], 'dihedrals': [0, 1, 2, 3], 'nbfix': [0, 1], 'nonbonded': [0], 'improper': [0, 1, 2, 3], 'impropers': [0, 1, 2, 3]})¶: Define the columns for each DataFrame which hold its index

COLUMNS: Mapping[str, Tuple[Union[None, int, float], …]] = mappingproxy({'atoms': (None, -1, None, nan), 'bonds': (None, None, nan, nan), 'angles': (None, None, None, nan, nan, nan, nan), 'dihedrals': (None, None, None, None, nan, -1, nan), 'nbfix': (None, None, nan, nan, nan, nan), 'nonbonded': (None, nan, nan, nan, nan, nan, nan), 'improper': (None, None, None, None, nan, 0, nan), 'impropers': (None, None, None, None, nan, 0, nan)})¶: Placeholder values for DataFrame columns

__init__(filename=None, atoms=None, bonds=None, angles=None, dihedrals=None, improper=None, impropers=None, nonbonded=None, nonbonded_header=None, nbfix=None, hbond=None)[source]¶: Initialize a PRMContainer instance.

property improper¶

Alias for PRMContainer.impropers.

Return type:	`Optional`[`DataFrame`]

static _is_mapping(value)[source]¶

Check if value is a dict instance; raise a TypeError if not.

Return type:	`dict`

__repr__()[source]¶

Return a (machine readable) string representation of this instance.

The string representation consists of this instances’ class name in addition to all (non-private) instance variables.

Returns:	A string representation of this instance.
Return type:	`str`

See also

PRMContainer._PRIVATE_ATTR: A set with the names of private instance variables.
PRMContainer._repr_fallback: Fallback function for PRMContainer.__repr__() incase of recursive calls.
PRMContainer._str_iterator(): Return an iterable for the iterating over this instances’ attributes.
PRMContainer._str(): Returns a string representation of a single key/value pair.

__eq__(value)[source]¶

Check if this instance is equivalent to value.

The comparison checks if the class type of this instance and value are identical and if all (non-private) instance variables are equivalent.

Returns:	Whether or not this instance and value are equivalent.
Return type:	`bool`

See also

PRMContainer._PRIVATE_ATTR: A set with the names of private instance variables.
PRMContainer._eq: Return if v1 and v2 are equivalent.
PRMContainer._eq_fallback: Fallback function for PRMContainer.__eq__() incase of recursive calls.

copy(deep=True)[source]¶

Return a shallow or deep copy of this instance.

Parameters:	deep (`bool`) – Whether or not to return a deep or shallow copy.
Returns:	A new instance constructed from this instance.
Return type:	`PRMContainer`

__copy__()[source]¶

Return a shallow copy of this instance; see PRMContainer.copy().

Return type:	~AT

classmethod read(filename, encoding=None, **kwargs)[source]¶

Construct a new instance from this object’s class by reading the content of filename.

Parameters:

filename (str, bytes, os.PathLike or a file object) – The path+filename or a file object of the to-be read .psf file. In practice, any iterable can substitute the role of file object as long iteration returns either strings or bytes (see encoding).
encoding (str, optional) – Encoding used to decode the input (e.g. "utf-8"). Only relevant when a file object is supplied to filename and the datastream is not in text mode.
**kwargs (Any) – Optional keyword arguments that will be passed to both PRMContainer._read_iterate() and PRMContainer._read_postprocess().

See also

PRMContainer._read_iterate(): An abstract method for parsing the opened file in PRMContainer.read().
PRMContainer._read_postprocess(): Post processing the class instance created by PRMContainer.read().

Return type:	`PRMContainer`

classmethod _read_iterate(iterator)[source]¶

An abstract method for parsing the opened file in read.

Parameters:	iterator (`Iterator` [`str`]) – An iterator that returns `str` instances upon iteration.
Return type:	`Dict`[`str`, `Any`]
Returns:	`dict` [`str`, `Any`] – A dictionary with keyword arguments for a new instance of this objects’ class. **kwargs (`Any`) – Optional keyword arguments.

See also

read(): The main method for reading files.

classmethod _read_post_iterate(kwargs)[source]¶

Post process the dictionary produced by PRMContainer._read_iterate().

Return type:	`None`

_read_postprocess(filename, encoding=None, **kwargs)[source]¶

Post processing the class instance created by read().

Parameters:

filename (str, bytes, os.PathLike or a file object) – The path+filename or a file object of the to-be read .psf file. In practice, any iterable can substitute the role of file object as long iteration returns either strings or bytes (see encoding).
encoding (str, optional) – Encoding used to decode the input (e.g. "utf-8"). Only relevant when a file object is supplied to filename and the datastream is not in text mode.
**kwargs (Any) – Optional keyword arguments that will be passed to both PRMContainer._read_iterate() and PRMContainer._read_postprocess().

See also

PRMContainer.read(): The main method for reading files.

Return type:	`None`

write(filename=None, encoding=None, **kwargs)[source]¶

Write the content of this instance to filename.

Parameters:

filename (str, bytes, os.PathLike or a file object) – The path+filename or a file object of the to-be read .psf file. Contrary to _read_postprocess(), file objects can not be substituted for generic iterables.
encoding (str, optional) – Encoding used to decode the input (e.g. "utf-8"). Only relevant when a file object is supplied to filename and the datastream is not in text mode.
**kwargs (Any) – Optional keyword arguments that will be passed to _write_iterate().

See also

PRMContainer._write_iterate(): Write the content of this instance to an opened datastream.
PRMContainer._get_writer(): Take a write() method and ensure its first argument is properly encoded.

Return type:	`None`

__hash__(self)¶

Return the hash of this instance.

The returned hash is constructed from two components: * The hash of this instances’ class type. * The hashes of all key/value pairs in this instances’ (non-private) attributes.

If an unhashable instance variable is encountered, e.g. a list, then its id() is used for hashing.

This method will raise a TypeError if the class attribute AbstractDataClass._HASHABLE is False.

See also

AbstractDataClass._PRIVATE_ATTR: A set with the names of private instance variables.
AbstractDataClass._HASHABLE: Whether or not this class is hashable.
AbstractDataClass._hash_fallback: Fallback function for AbstractDataClass.__hash__() incase of recursive calls.
AbstractDataClass._hash: An instance variable for caching the hash() of this instance.

Return type:	`int`

__weakref__¶: list of weak references to the object (if defined)

_write_iterate(write, **kwargs)[source]¶

Write the content of this instance to an opened datastream.

The to-be written content of this instance should be passed as str. Any (potential) encoding is handled by the write parameter.

Example

Basic example of a potential _write_iterate() implementation.

>>> iterator = self.as_dict().items()
>>> for key, value in iterator:
...     value: str = f'{key} = {value}'
...     write(value)
>>> return None

Parameters:	writer (`Callable`) – A callable for writing the content of this instance to a file object. An example would be the `io.TextIOWrapper.write()` method. *kwargs (optional*) – Optional keyword arguments.

See also

PRMContainer.write(): The main method for writing files.

Return type:	`None`

overlay_mapping(prm_name, param_df, units=None)[source]¶

Update a set of parameters, prm_name, with those provided in param_df.

Examples

>>> from FOX import PRMContainer

>>> prm = PRMContainer(...)

>>> param_dict = {}
>>> param_dict['epsilon'] = {'Cd Cd': ..., 'Cd Se': ..., 'Se Se': ...}  # epsilon
>>> param_dict['sigma'] = {'Cd Cd': ..., 'Cd Se': ..., 'Se Se': ...}  # sigma

>>> units = ('kcal/mol', 'angstrom')  # input units for epsilon and sigma

>>> prm.overlay_mapping('nonbonded', param_dict, units=units)

Parameters:

prm_name (str) – The name of the parameter of interest. See the keys of PRMContainer.CP2K_TO_PRM for accepted values.
param_df (pandas.DataFrame or nested Mapping) – A DataFrame or nested mapping with the to-be added parameters. The keys should be a subset of PRMContainer.CP2K_TO_PRM[prm_name]["columns"]. If the index/nested sub-keys consist of strings then they’ll be split and turned into a pandas.MultiIndex. Note that the resulting values are not sorted.
units (Iterable [str], optional) – An iterable with the input units of each column in param_df. If None, default to the defaults specified in PRMContainer.CP2K_TO_PRM[prm_name]["unit"].

Return type:

None

overlay_cp2k_settings(cp2k_settings)[source]¶

Extract forcefield information from PLAMS-style CP2K settings.

Performs an inplace update of this instance.

Examples

Example input value for cp2k_settings. In the provided example the cp2k_settings are directly extracted from a CP2K .inp file.

>>> import cp2kparser  # https://github.com/nlesc-nano/CP2K-Parser

>>> filename = str(...)

>>> cp2k_settings: dict = cp2kparser.read_input(filename)
>>> print(cp2k_settings)
{'force_eval': {'mm': {'forcefield': {'nonbonded': {'lennard-jones': [...]}}}}}

Parameters:	cp2k_settings (`Mapping`) – A Mapping with PLAMS-style CP2K settings.

See also

PRMMapping: PRMMapping A mapping providing tools for converting CP2K settings to .prm-compatible values.

Return type:	`None`

_overlay_cp2k_settings(cp2k_settings, name, columns, key_path, key, unit, default_unit, post_process)[source]¶

Helper function for PRMContainer.overlay_cp2k_settings().

Return type:	`None`