Properties¶

Functions for calculating/extracting various properties.

Each function can be used to calculate the respective property as is, or to extract it from a passed qmflows.Result instance.

>>> from FOX.properties import get_bulk_modulus
>>> from qmflows.packages import Result
>>> import numpy as np

>>> # Calculate the bulk modulus from a set of arrays
>>> pressure: np.ndarray = ...
>>> volume: np.ndarray = ...
>>> get_bulk_modulus(pressure, volume)  
array([[[ 0.,  1.,  2.],
        [ 3.,  4.,  5.]],

       [[ 6.,  7.,  8.],
        [ 9., 10., 11.]]])

>>> # Calculate the bulk modulus from a qmflows.Result instance
>>> result: Result = ...
>>> get_bulk_modulus.from_result(result)  
array([[[ 0.,  1.,  2.],
        [ 3.,  4.,  5.]],

       [[ 6.,  7.,  8.],
        [ 9., 10., 11.]]])

An example for how get_bulk_modulus() can be used in conjunction with the ARMC yaml input. Note that additional CP2K print keys are required in order for it to export the necessary properties.

job:
    type: FOX.armc.PackageManager
    molecule: mol.xyz

    md:
        template: qmflows.md.specific.cp2k_mm
        settings:
            cell_parameters: [50, 50, 50]
            input:
                motion:
                    print:
                        cell on:
                            filename: ''
                        forces on:
                            filename: ''
                    md:
                        ensemble: NVE
                        thermostat:
                            print:
                                temperature on:
                                    filename: ''

pes:
    bulk_modulus:
        func: FOX.properties.get_bulk_modulus.from_result
        ref: [1.0]
        kwargs:
            reduce: mean

Index¶

`FromResult` (func, name[, module, doc])	A class for wrapping `Callable` objects.
`get_attr` (obj, name[, default, reduce, axis])	`gettattr()` with support for keyword argument.
`call_method` (obj, name, *args[, reduce, axis])	Call the name method of obj.
`get_pressure` (forces, coords, volume[…])	Calculate the pressure from the passed forces.
`get_bulk_modulus` (pressure, volume[…])	Calculate the bulk modulus via differentiation of pressure w.r.t. volume.

API¶

class FOX.properties.FromResult(func, name, module=None, doc=None)[source]¶

An abstract base class for wrapping Callable objects.

Besides __call__(), instances have access to the from_result() method, which is used for applying the wrapped callable to a qmflows.Result instance.

Parameters:	func (`Callable[..., Any]`) – The to-be wrapped function. name (`str`) – The `__name__` attribute of the to-be created instance. module (`str`) – The `__module__` attribute of the to-be created instance. If `None`, set it to `"__main__"`. doc (`str`, optional) – The `__doc__` attribute of the to-be created instance. If `None`, extract the docstring from func.

REDUCTION_NAMES : Mapping[str, Callable[[np.ndarray], np.float64]] = ...¶

A mapping that maps from_result() aliases to callbacks.

In addition to the examples below, all reducable ufuncs from numpy and scipy.special are available.

>>> from types import MappingProxyType
>>> import numpy as np
>>> import scipy.special

>>> REDUCTION_NAMES = MappingProxyType({
...     'min': np.min,
...     'max': np.max,
...     'mean': np.mean,
...     'sum': np.sum,
...     'product': np.product,
...     'var': np.var,
...     'std': np.std,
...     'ptp': np.ptp,
...     'norm': np.linalg.norm,
...     'argmin': np.argmin,
...     'argmax': np.argmax,
...     'all': np.all,
...     'any': np.any,
...     'add': np.add.reduce,
...     'eval_legendre': scipy.special.eval_legendre.reduce,
...     ...
... })

property __call__¶: Get the underlying function.

abstract from_result(result, reduce=None, axis=None, *, return_unit=NotImplemented, **kwargs)[source]¶

Call self using argument extracted from result.

Parameters:	result (`qmflows.Result`) – The Result instance that self should operator on. reduce (`str` or `Callable[[Any], Any]`, optional) – A callback for reducing the output of self. Alternativelly, one can provide on of the string aliases from `REDUCTION_NAMES`. axis (`int` or `Sequence[int]`, optional) – The axis along which the reduction should take place. If `None`, use all axes. return_unit (`str`) – The unit of the to-be returned quantity. **kwargs (`Any`) – Further keyword arguments for `__call__()`.
Returns:	The output of `__call__()`.
Return type:	`Any`

FOX.properties.get_attr(obj, name, default=<null>, reduce=None, axis=None)[source]¶

gettattr() with support for keyword argument.

Parameters:	obj (`object`) – The object in question. name (`str`) – The name of the to-be extracted attribute. default (`Any`) – An object that is to-be returned if obj does not have the name attribute. reduce (`str` or `Callable[[Any], Any]`, optional) – A callback for reducing the extracted attribute. Alternativelly, one can provide on of the string aliases from `FromResult.REDUCTION_NAMES`. axis (`int` or `Sequence[int]`, optional) – The axis along which the reduction should take place. If `None`, use all axes.
Returns:	The extracted attribute.
Return type:	`Any`

See also

getattr(): Get a named attribute from an object.

FOX.properties.call_method(obj, name, *args, reduce=None, axis=None, **kwargs)[source]¶

Call the name method of obj.

Parameters:	obj (`object`) – The object in question. name (`str`) – The name of the to-be extracted method. args/kwargs (`Any`) – Positional and/or keyword arguments for the (to-be called) extracted method. reduce* (`str` or `Callable[[Any], Any]`, optional) – A callback for reducing the output of the called function. Alternativelly, one can provide on of the string aliases from `FromResult.REDUCTION_NAMES`. axis (`int` or `Sequence[int]`, optional) – The axis along which the reduction should take place. If `None`, use all axes.
Returns:	The output of the extracted method.
Return type:	`Any`

FOX.properties.get_pressure(forces, coords, volume, temp=298.15, forces_unit='ha/bohr', coords_unit='bohr', volume_unit='bohr', return_unit='ha/bohr^3')¶

Calculate the pressure from the passed forces.

\[P = \frac{Nk_{B}T}{V} + \frac{1}{6V} \sum_i^N \sum_j^N {\boldsymbol{r}_{ij} \cdot \boldsymbol{f}_{ij}}\]

Parameters:	forces (`np.ndarray[np.float64]`, shape \((n_{\text{mol}}, n_{\text{atom}}, 3)\)) – A 3D array containing the forces of all molecules within the trajectory. coords (`np.ndarray[np.float64]`, shape \((n_{\text{mol}}, n_{\text{atom}}, 3)\)) – A 3D array containing the coordinates of all molecules within the trajectory. volume (`np.ndarray[np.float64]`, shape \((n_{\text{mol}},)\)) – A 1D array containing the cell volumes across the trajectory. temp (`np.ndarray[np.float64]`, shape \((n_{\text{mol}},)\)) – A 1D array of the temperatures across the trajectory. forces_unit (`str`) – The unit of the forces. coords_unit (`str`) – The unit of the coords. volume_unit (`str`) – The unit of the volume. The passed unit will automatically cubed, e.g. `Angstrom -> Angstrom3`. return_unit** (`str`) – The unit of the to-be returned pressure.
Returns:	A 1D array with all pressures across the trajectory.
Return type:	`np.ndarray[np.float64]`, shape \((n_{\text{mol}},)\)

Note

Using get_pressure.from_result() requires the passed qmflows.CP2K_Result to have access to the following files for each argument:

forces: cp2k-frc-1.xyz
coords: cp2k-pos-1.xyz
volume: cp2k-1.cell
temp: cp2k-1.ener

FOX.properties.get_bulk_modulus(pressure, volume, pressure_unit='ha/bohr^3', volume_unit='bohr', return_unit='ha/bohr^3')¶

Calculate the bulk modulus via differentiation of pressure w.r.t. volume.

\[B = -V * \frac{\delta P}{\delta V}\]

Parameters:	pressure (`np.ndarray[np.float64]`) – A 1D array of pressures used for defining \(\delta P\). Must be of equal length as volume. volume (`np.ndarray[np.float64]`) – A 1D array of volumes used for defining \(\delta V\). Must be of equal length as pressure. pressure_unit (`str`) – The unit of the pressure. volume_unit (`str`) – The unit of the volume. The passed unit will automatically cubed, e.g. `Angstrom -> Angstrom3`. return_unit** (`str`) – The unit of the to-be returned pressure.
Returns:	The bulk modulus \(B\). Returend as either a scalar or array, depending on the dimensionality volume_ref.
Return type:	`np.float64` or `np.ndarray[np.float64]`

Note

Using get_bulk_modulus.from_result() requires the passed qmflows.CP2K_Result to have access to the following files for each argument:

pressure: *.out (expected unit: bar)
volume: cp2k-1.cell (expected unit: angstrom**3)

Furthermore, in order to get sensible results both the pressure and cell volume must be variable.