chemcoord.Zmat.get_grad_cartesian

Zmat.get_grad_cartesian(as_function=True, chain=True, drop_auto_dummies=True)

Return the gradient for the transformation to a Cartesian.

If as_function is True, a function is returned that can be directly applied onto instances of Zmat, which contain the applied distortions in Zmatrix space. In this case the user does not have to worry about indexing and correct application of the tensor product. Basically this is the function zmat_functions.apply_grad_cartesian_tensor() with partially replaced arguments.

If as_function is False, a (3, n, n, 3) tensor is returned, which contains the values of the derivatives.

Since a n * 3 matrix is deriven after a n * 3 matrix, it is important to specify the used rules for indexing the resulting tensor.

The rule is very simple: The indices of the numerator are used first then the indices of the denominator get swapped and appended:

\[\left( \frac{\partial \mathbf{Y}}{\partial \mathbf{X}} \right)_{i, j, k, l} = \frac{\partial \mathbf{Y}_{i, j}}{\partial \mathbf{X}_{l, k}}\]

Applying this rule to an example function:

\[f \colon \mathbb{R}^3 \rightarrow \mathbb{R}\]

Gives as derivative the known row-vector gradient:

\[(\nabla f)_{1, i} = \frac{\partial f}{\partial x_i} \qquad i \in \{1, 2, 3\}\]

Note

The row wise alignment of the zmat files makes sense for these CSV like files. But it is mathematically advantageous and sometimes (depending on the memory layout) numerically better to use a column wise alignment of the coordinates. In this function the resulting tensor assumes a 3 * n array for the coordinates.

If

\[\begin{split}\mathbf{C}_{i, j} &\qquad 1 \leq i \leq 3, \quad 1 \leq j \leq n \\ \mathbf{X}_{i, j} &\qquad 1 \leq i \leq 3, \quad 1 \leq j \leq n\end{split}\]

denote the positions in Zmatrix and cartesian space,

The complete tensor may be written as:

\[\left( \frac{\partial \mathbf{X}}{\partial \mathbf{C}} \right)_{i, j, k, l} = \frac{\partial \mathbf{X}_{i, j}}{\partial \mathbf{C}_{l, k}}\]
Parameters:
  • construction_table (pandas.DataFrame) –
  • as_function (bool) – Return a tensor or xyz_functions.apply_grad_zmat_tensor() with partially replaced arguments.
  • chain (bool) –
  • drop_auto_dummies (bool) – Drop automatically created dummies from the gradient. This means, that only changes in regularly placed atoms are considered for the gradient.
Returns:

Depending on as_function return a tensor or apply_grad_cartesian_tensor() with partially replaced arguments.
Return type:

(func, numpy.ndarray)