Cartesian.get_grad_zmat(construction_table, as_function=True)

Return the gradient for the transformation to a Zmatrix.

If as_function is True, a function is returned that can be directly applied onto instances of Cartesian, which contain the applied distortions in cartesian 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 xyz_functions.apply_grad_zmat_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\}\]


The row wise alignment of the XYZ 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.


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

denote the positions in cartesian and Zmatrix space,

The complete tensor may be written as:

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

Depending on as_function return a tensor or apply_grad_zmat_tensor() with partially replaced arguments.

Return type:

(func, np.array)