add the hkl.org file with all the documentation

[hkl.git] / Documentation / hkl.org.in

* Welcome to hkl's @VERSION@ documentation!
* Introduction

The purpose of the library is to factorise single crystal diffraction
angles computation for different kind of diffractometer geometries. It
is used at the SOLEIL, Desy and Alba synchrotron with the Tango control
system to pilot diffractometers.

** Features

-  mode computation (aka PseudoAxis)

   -  item for different diffractometer geometries.

-  UB matrix computation.

   -  busing & Levy with 2 reflections
   -  simplex computation with more than 2 reflections using the GSL
      library.
   -  Eulerians angles to pre-orientate your sample.

-  Crystal lattice affinement

   -  with more than 2 reflections you can select which parameter must
      be fitted.

-  Pseudoaxes

   -  psi, eulerians, q, ...

** Conventions

In all this document the next convention will be used to describe the
diffractometers geometries.

-  right handed convention for all the angles.
-  direct space orthogonal base.
-  description of the diffractometer geometries is done with all axes
   values set to zero.

** Diffraction
*** the crystal

A periodic crystal is the association of a pattern and a lattice. The
pattern is located at each points of the lattice node. Positions of
those nodes are given by:

$$R_{uvw}=u\cdot\vec{a}+v\cdot\vec{b}+w\cdot\vec{c}$$

$\vec{a}$, $\vec{b}$, $\vec{c}$ are the former vector of a base of the
space. =u=, =v=, =w= are integrers. The pattern contain atomes
associated to each lattice node. the purpose of diffraction is to study
the interaction of this crystal (pattern+lattice) with X-rays.

#+CAPTION: Crystal direct lattice.

[[../../figures/crystal.png]]
this lattice is defined by $\vec{a}$, $\vec{b}$, $\vec{c}$ vectors, and
the angles $\alpha$, $\beta$, $\gamma$. In general cases this lattice is
not othonormal.

Nevertheless to compute the interaction of this real space lattice and
the X-Rays, it is convenient to define another lattice called reciprocal
lattice defined like this:

$$\begin{eqnarray*}
 \vec{a}^{\star} & = & \tau\frac{\vec{b}\wedge\vec{c}}{\vec{a}\cdot(\vec{b}\wedge\vec{c})}\\
 \vec{b}^{\star} & = & \tau\frac{\vec{c}\wedge\vec{a}}{\vec{b}\cdot(\vec{c}\wedge\vec{a})}\\
 \vec{c}^{\star} & = & \tau\frac{\vec{a}\wedge\vec{b}}{\vec{c}\cdot(\vec{a}\wedge\vec{b})} 
\end{eqnarray*}$$

$\tau=2\pi$ or $\tau=1$ depending on the conventions.

It is then possible to define thoses orthogonal properties:

$$\begin{eqnarray*}
 \vec{a}^{\star}\cdot\vec{a}=\tau & \vec{b}^{\star}\cdot\vec{a}=0    & \vec{c}^{\star}\cdot\vec{a}=0\\
 \vec{a}^{\star}\cdot\vec{b}=0    & \vec{b}^{\star}\cdot\vec{b}=\tau & \vec{c}^{\star}\cdot\vec{b}=0\\
 \vec{a}^{\star}\cdot\vec{c}=0    & \vec{b}^{\star}\cdot\vec{c}=0    & \vec{c}^{\star}\cdot\vec{c}=\tau 
\end{eqnarray*}$$

This reciprocal space lattice allow to write in a simpler form the
interaction between the crystal and the X-Rays. We often only know about
$\vec{a}$, $\vec{b}$, $\vec{c}$ vectors and the angles $\alpha$,
$\beta$, $\gamma$. Using the previous equations reciprocal, we can
compute the reciprocal lattice this way:

$$\begin{eqnarray*}
 a^{\star} & = & \frac{\sin\alpha}{aD}\\
 b^{\star} & = & \frac{\sin\beta}{bD}\\
 c^{\star} & = & \frac{\sin\gamma}{cD}
\end{eqnarray*}$$

where

$$D=\sqrt{1-\cos^{2}\alpha-\cos^{2}\beta-\cos^{2}\gamma+2\cos\alpha\cos\beta\cos\gamma}$$

To compute the angles between the reciprocal space vectors, it is once
again possible to use the previous equations reciprocal to obtain the
sinus and cosinus of the angles $\alpha^\star$, $\beta^\star$ et
$\gamma^\star$:

$$\begin{eqnarray*}
 \cos\alpha^{\star}=\frac{\cos\beta\cos\gamma-\cos\alpha}{\sin\beta\sin\gamma} & \, & \sin\alpha^{\star}=\frac{D}{\sin\beta\sin\gamma} \\
 \cos\beta^{\star}=\frac{\cos\gamma\cos\alpha-\cos\beta}{\sin\gamma\sin\alpha} & \, & \sin\beta^{\star}=\frac{D}{\sin\gamma\sin\alpha}\\
 \cos\gamma^{\star}=\frac{\cos\alpha\cos\beta-\cos\gamma}{\sin\alpha\sin\beta} & \, & \sin\gamma^{\star}=\frac{D}{\sin\alpha\sin\beta}
\end{eqnarray*}$$

*** Diffraction

Let the incomming X-rays beam whose wave vector is $\vec{k_{i}}$,
$|k_{i}|=\tau/\lambda$ where $\lambda$ is the wavelength of the signal.
The $\vec{k_{d}}$ vector wavelength of the diffracted beam. There is
diffusion if the diffusion vector $\vec{q}$ can be expressed as follows:

$$\vec{q}=\vec{k_{d}}-\vec{k_{i}}=h.\vec{a}^{*}+k.\vec{b}^{*}+l.\vec{c}^{*}$$

where $(h,k,l)\in\mathbb{N}^{3}$ and $(h,k,l)\neq(0,0,0)$. Thoses
indices $(h,k,l)$ are named Miller indices.

Another way of looking at things has been given by Bragg and that famous
relationship:

$$n\lambda=2d\sin\theta$$

where $d$ is the inter-plan distance and $n \in
\mathbb{N}$.

The diffusion accure for a unique $\theta$ angle. Then we got $\vec{q}$
perpendicular to the diffraction plan.

The Ewald construction allow to represent this diffraction in the
reciprocal space.

*** Quaternions

**** Properties

The quaternions will be used to discribe the diffractometers geometries.
Thoses quaternions can represent 3D rotations. There is different way to
describe then like complex numbers.

$$q=a+bi+cj+dk$$

or

$$q=[a,\vec{v}]$$

To compute the quaternion's norm, we can proceed like for complex
numbers

$$\lvert q \rvert = \sqrt{a{{}^2}+b{{}^2}+c{{}^2}+d{{}^2}}$$

Its conjugate is :

$$q^{*}=[a,-\vec{u}]=a-bi-cj-dk$$

**** Operations

The difference with the complexnumber algebre is about
non-commutativity.

$$qp \neq pq$$

$$\bordermatrix{
 ~ & 1 & i  & j  & k \cr
 1 & 1 & i  & j  & k \cr
 i & i & -1 & k  & -j \cr
 j & j & -k & -1 & i \cr
 k & k & j  & -i & -1
}$$

The product of two quaternions can be express by the Grassman product
Grassman product. So for two quaternions $p$ and $q$:

$$\begin{align*}
 q &= a+\vec{u} = a+bi+cj+dk\\
 p &= t+\vec{v} = t+xi+yj+zk
\end{align*}$$

we got

$$pq=at-\vec{u}\cdot\vec{v}+a\vec{v}+t\vec{u}+\vec{v}\times\vec{u}$$

or equivalent

$$pq=(at-bx-cy-dz)+(bt+ax+cz-dy)i+(ct+ay+dx-bz)j+(dt+az+by-cx)k$$

**** 3D rotations

L'ensemble des quaternions unitaires (leur norme est égale à 1) est le
groupe qui représente les rotations dans l'espace 3D. Si on a un vecteur
unitaire $\vec{u}$ et un angle de rotation $\theta$ alors le quaternion
$[\cos\frac{\theta}{2},\sin\frac{\theta}{2}\vec{u]}$ représente la
rotation de $\theta$ autour de l'axe $\vec{u}$ dans le sens
trigonométrique. Nous allons donc utiliser ces quaternions unitaires
pour représenter les mouvements du diffractomètre.

Alors que dans le plan 2D une simple multiplication entre un nombre
complex et le nombre $e^{i\theta}$ permet de calculer simplement la
rotation d'angle $\theta$ autour de l'origine, dans l'espace 3D
l'expression équivalente est:

$$z'=qzq^{-1}$$

où $q$ est le quaternion de norme 1 représentant la rotation dans
l'espace et $z$ le quaternion représentant le vecteur qui subit la
rotation (sa partie réelle est nulle).

Dans le cas des quaternions de norme 1, il est très facile de calculer
$q^{-1}$. En effet l'inverse d'une rotation d'angle $\theta$ est la
rotation d'angle $-\theta$. On a donc directement:

$$q^{-1}=[\cos\frac{-\theta}{2},\sin\frac{-\theta}{2}\vec{u}]=[\cos\frac{\theta}{2},-\sin\frac{\theta}{2}\vec{u}]=q^{*}$$

Le passage aux matrices de rotation se fait par la formule suivante
$q\rightarrow M$.

$$\begin{bmatrix}
 a{{}^2}+b{{}^2}-c{{}^2}-d{{}^2} & 2bc-2ad & 2ac+2bd\\
 2ad+2bc & a{{}^2}-b{{}^2}+c{{}^2}-d{{}^2} & 2cd-2ab\\
 2bd-2ac & 2ab+2cd & a{{}^2}-b{{}^2}-c{{}^2}+d{{}^2}
\end{bmatrix}$$

La composition de rotation se fait simplement en multipliant les
quaternions entre eux. Si l'on à $q$

** Modes de fonctionnement
** Equations fondamentales

Le problème que nous devons résoudre est de calculer pour une famille de
plan $(h,k,l)$ donné, les angles de rotation du diffractomètre qui
permettent de le mettre en condition de diffraction. Il faut donc
exprimer les relations mathématiques qui lient les différents angles
entre eux lorsque la condition de Bragg est vérifiée. L'équation
fondamentale est la suivante:

$$\begin{align*}
 \left(\prod_{i}S_{i}\right)\cdot U\cdot B\cdot\vec{h} & =\left(\prod_{j}D_{j}-I\right)\cdot\vec{k_{i}}\\
 R\cdot U\cdot B\cdot\vec{h} & =\vec{Q}
\end{align*}$$

ou $\vec{h}$ est le vecteur $(h,k,l)$, $\vec{k_{i}}$ est le vecteur
incident, $S_{i}$ les matrices de rotations des mouvements liés à
l'échantillon, $D_{j}$ les matrices de rotation des mouvements liés au
détecteur, $I$ la matrice identité, $U$ la matrice d'orientation du
cristal par rapport au repère de l'axe sur lequel ce dernier est monté
et $B$ la matrice de passage d'un repère non orthonormé ( celui du
crystal réciproque) à un repère orthonormé.

*** Calcule de B

Si l'on connaît les paramètres cristallins du cristal étudié, il est
très simple de calculer $B$:

$$B=
\begin{bmatrix}
 a^{\star} & b^{\star}\cos\gamma^{\star} & c^{\star}\cos\beta^{\star}\\
 0 & b^{\star}\sin\gamma^{\star} & -c^{\star}\sin\beta^{\star}\cos\alpha\\
 0 & 0 & 1/c
\end{bmatrix}$$

*** Calcule de U

Il existe plusieurs façons de calculer $U$. Busing et Levy en a proposé
plusieurs. Nous allons présenter celle qui nécessite la mesure de
seulement deux réflections ainsi que la connaissance des paramètres
cristallins. Cette façon de calculer la matrice d'orientation $U$, peut
être généralisée à n'importe quel diffractomètre pour peu que la
description des axes de rotation permette d'obtenir la matrice de
rotation de la machine $R$ et le vecteur de diffusion $\vec{Q}$.

Il est également possible de calculer $U$ sans la connaîssance des
paramètres cristallins. il faut alors faire un affinement des
paramètres. Cela revient à minimiser une fonction. Nous allons utiliser
la méthode du simplex pour trouver ce minimum et donc ajuster l'ensemble
des paramètres cristallins ainsi que la matrice d'orientation.

*** Algorithme de Busing Levy

L'idée est de se placer dans le repère de l'axe sur lequel est monté
l'échantillon. On mesure deux réflections $(\vec{h}_{1},\vec{h}_{2})$
ainsi que leurs angles associés. Cela nous permet de calculer $R$ et
$\vec{Q}$ pour chacune de ces reflections. nous avons alors ce système:

$$\begin{eqnarray*}
 U\cdot B\cdot\vec{h}_{1} & = & \tilde{R}_{1}\cdot\vec{Q}_{1}\\
 U\cdot B\cdot\vec{h}_{2} & = & \tilde{R}_{2}\cdot\vec{Q}_{2}
\end{eqnarray*}$$

De façon à calculer facilement $U$, il est intéressant de définir deux
trièdres orthonormé $T_{\vec{h}}$ et $T_{\vec{Q}}$ à partir des vecteurs
$(B\vec{h}_{1},B\vec{h}_{2})$ et
$(\tilde{R}_{1}\vec{Q}_{1},\tilde{R}_{2}\vec{Q}_{2})$. On a alors très
simplement:

$$U\cdot T_{\vec{h}}=T_{\vec{Q}}$$

Et donc

$$U=T_{\vec{Q}}\cdot\tilde{T}_{\vec{h}}$$

*** Affinement par la méthode du simplex

Dans ce cas nous ne connaissons pas la matrice $B$, il faut donc mesurer
plus que deux réflections pour ajuster les 9 paramètres. Six paramètres
pour le crystal et trois pour la matrice d'orientation $U$. Les trois
paramètres qui permennt de representer $U$ sont en fait les angles
d'euler. il faut donc être en mesure de passer d'une représentation
eulérien à cette matrice :math::U et réciproquement.

$$U=X\cdot Y\cdot Z$$

où $X$ est la matrice rotation suivant l'axe Ox et le premier angle
d'Euler, $Y$ la matrice de rotation suivant l'axe Oy et le deuxième
angle d'Euler et $Z$ la matrice du troisième angle d'Euler pour l'axe
Oz.

$$\begin{tabular}{ccc}
 $X$ & $Y$ & $Z$\tabularnewline
 $\begin{bmatrix}
     1 & 0 & 0\\
     0 & A & -B\\
     0 & B & A
 \end{bmatrix}$
 &
 $\begin{bmatrix}
     C & 0 & D\\
     0 & 1 & 0\\
     -D & 0 & C
 \end{bmatrix}$
 &
 $\begin{bmatrix}
     E & -F & 0\\
     F & E & 0\\
     0 & 0 & 1
 \end{bmatrix}$
\end{tabular}$$

et donc:

$$U=
\begin{bmatrix}
 CE & -CF & D\\
 BDE+AF & -BDF+AE & -BC\\
 -ADE+BF & ADF+BE & AC
\end{bmatrix}$$

Il est donc facile de passer des angles d'Euler à la matrice
d'orientation.

Il faut maintenant faire la transformation inverse de la matrice $U$
vers les angles d'euler.

** Diffractomètre 4 Cercle (3S+1D) Eulerien

Pour ce diffractomètres, les matrices de rotations des différents axes
sont les suivantes:

$$\begin{tabular}{cccc}
 $\Omega$ & $\chi$ & $\Phi$ & $2\Theta$\tabularnewline
 $\begin{bmatrix}
     \cos\omega & 0 & -\sin\omega\\
     0 & 1 & 0\\
     \sin\omega & 0 & \cos\omega
 \end{bmatrix}$
 &
 $\begin{bmatrix}
     1 & 0 & 0\\
     0 & \cos\chi & -\sin\chi\\
     0 & \sin\chi & \cos\chi
 \end{bmatrix}$
 &
 $\begin{bmatrix}
     \cos\phi & 0 & -\sin\phi\\
     0 & 1 & 0\\
     \sin\phi & 0 & \cos\phi
 \end{bmatrix}$
 &
 $\begin{bmatrix}
     \cos2\theta & 0 & -\sin2\theta\\
     0 & 1 & 0\\
     \sin2\theta & 0 & \cos2\theta
 \end{bmatrix}$
\end{tabular}$$

On obtient alors la matrice de rotation de la machine

$$R=\Omega\chi\Phi$$

soit

$$R=
\begin{bmatrix}
 \cos\omega\cos\phi-\cos\chi\sin\omega\sin\phi & -\sin\chi\sin\omega & -\cos\omega\sin\phi-\cos\chi\sin\omega\cos\phi\\
 -\sin\chi\sin\phi & \cos\chi & -\sin\chi\cos\phi\\
 \sin\omega\cos\phi-\cos\chi\cos\omega\sin\phi & -\sin\chi\cos\omega & -\sin\omega\sin\phi-\cos\chi\cos\omega\cos\phi
\end{bmatrix}$$

De la même façon on peut calculer le vecteur diffusion en fonction des
angles du détecteur:

$$\vec{Q}=\left(2\Theta-I\right)\cdot\vec{k}_{i}$$

où $I$ est la matrice identité. Finalement:

$$\vec{Q}=k_{i}\left(\begin{array}{c}
\cos2\theta-1\\
0\\
\sin2\theta
\end{array}\right)$$

L'équation fondamentale nous permet d'écrire:

$$U\cdot B\cdot\vec{h}=\tilde{R}\cdot\vec{Q}$$

Cette équation est de 4 inconnus pour seulement 3 équations. Il faut
donc imposer des contraintes pour résoudre ce système et ainsi
d'orienter le diffractomètre. Ces différentes contraintes définissent
les modes de fonctionnement des diffractomètres. Dans la suite nous
allons nous efforcer de trouver l'ensemble des solutions possibles pour
les différents modes et non pas une seule solution. Ceci afin de laisser
le choix suivant certaines stratégies à l'utilisateur d'utiliser telle
ou telle solution plutôt qu'une autre.

*** Mode Bisecteur

Dans ce mode on choisit d'avoir:

$$\omega=\theta$$

Le système s'écrit alors simplement:

$$\begin{eqnarray*}
 h_{\phi} & = & 2k_{i}\sin\theta\cos\chi\sin\phi\\
 k_{\phi} & = & 2k_{i}\sin\theta\sin\chi\\
 l_{\phi} & = & 2k_{i}\sin\theta\cos\chi\cos\phi
\end{eqnarray*}$$

On a:

$$h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}=4k_{i}\sin^{2}\theta$$

où $k_{i}=\frac{\tau}{\lambda}$. donc on peut écrire:

$$\left|\sin\theta\right|=\frac{\sqrt{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}}{2k_{i}}$$

il faut donc enviseager les deux possibilité selon que $\theta$ est
positif ou bien négatif.

$$\sin\theta<0$$

On peut alors écrire:

$$\sin\chi=-\frac{k_{\phi}}{\sqrt{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}}$$

puis en utilisant le relation bien connue $\cos^{2}+\sin^{2}=1$ on a:

$$\cos^{2}\chi=\frac{h_{\phi}^{2}+l_{\phi}^{2}}{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}$$

Il faut une fois de plus faire un choix selon que $\cos\chi$ est positif
ou négatif.

$$\cos\chi<0$$

$$\cos\chi=-\sqrt{\frac{h_{\phi}^{2}+l_{\phi}^{2}}{h_{\phi}^{2}+k_{\phi+}^{2}l_{\phi}^{2}}}$$

$$\cos\chi>0$$

$$\cos\chi=\sqrt{\frac{h_{\phi}^{2}+l_{\phi}^{2}}{h_{\phi}^{2}+k_{\phi+}^{2}l_{\phi}^{2}}}$$

$$\sin\theta>0$$

On peut alors écrire:

$$\sin\chi=\frac{k_{\phi}}{\sqrt{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}}$$

puis en utilisant le relation bien connue $\cos^{2}+\sin^{2}=1$ on a:

$$\cos^{2}\chi=\frac{h_{\phi}^{2}+l_{\phi}^{2}}{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}$$

Il faut une fois de plus faire un choix selon que $\cos\chi$ est positif
ou négatif.

$$\cos\chi<0$$

$$\cos\chi=-\sqrt{\frac{h_{\phi}^{2}+l_{\phi}^{2}}{h_{\phi}^{2}+k_{\phi+}^{2}l_{\phi}^{2}}}$$

$$\cos\chi>0$$

$$\cos\chi=\sqrt{\frac{h_{\phi}^{2}+l_{\phi}^{2}}{h_{\phi}^{2}+k_{\phi+}^{2}l_{\phi}^{2}}}$$

La résolution du système donne alors 4 quadruplets de solutions:

$$\begin{tabular}{c|c|c|c}
 $\omega$ & $\chi$ & $\phi$ & $2\theta$\tabularnewline
 \hline
 $-\theta$ & $\arctan2(-k_{\phi},-\sqrt{h_{\phi}^{2}+l_{\phi}^{2}})$ & $\arctan2(h_{\phi},l_{\phi})$ & $2\arcsin-\frac{\sqrt{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}}{2k_{i}}$\tabularnewline
 $-\theta$ & $\arctan2(-k_{\phi},\sqrt{h_{\phi}^{2}+l_{\phi}^{2}})$ & $\arctan2(-h_{\phi},-l_{\phi})$ & $2\arcsin-\frac{\sqrt{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}}{2k_{i}}$\tabularnewline
 $\theta$ & $\arctan2(k_{\phi},-\sqrt{h_{\phi}^{2}+l_{\phi}^{2}})$ & $\arctan2(-h_{\phi},-l_{\phi})$ & $2\arcsin\frac{\sqrt{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}}{2k_{i}}$\tabularnewline
 $\theta$ & $\arctan2(k_{\phi},\sqrt{h_{\phi}^{2}+l_{\phi}^{2}})$ & $\arctan2(h_{\phi},l_{\phi})$ & $2\arcsin\frac{\sqrt{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}}{2k_{i}}$\tabularnewline
\end{tabular}$$

*** Mode Delta Theta

Ce mode consiste à décaler $\omega$ par rapport à $\theta$ d'une valeur
constante $C$:

$$\omega=\theta+C$$

Le système s'écrit alors comme suit:

$$\begin{eqnarray*}
 h_{\phi} & = & 2k_{i}\sin\theta\left(\cos C\cos\chi\sin\phi+\sin C\cos\phi\right)\\
 k_{\phi} & = & 2k_{i}\sin\theta\cos C\sin\chi\\
 l_{\phi} & = & 2k_{i}\sin\theta\left(\cos C\cos\chi\cos\phi-\sin C\sin\phi\right)
\end{eqnarray*}$$

On a toujours:

$$h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}=4k_{i}\sin^{2}\theta$$

La résolution donne 4 quadruplets de solutions:

$$\begin{tabular}{ccc}
    $\omega$ & $\chi$ & $\phi$\tabularnewline
    \hline
    $-\theta+C$ & $\arctan2(\frac{-k_{\phi}}{\cos C},-\sqrt{h_{\phi}^{2}-k_{\phi}^{2}\tan^{2}C+l_{\phi}^{2}})$ & $\arctan2(-h_{\phi}\cos C\cos\chi+l_{\phi}\sin C,-l_{\phi}\cos C\cos\chi-h_{\phi}\sin C)$\tabularnewline
    $-\theta+C$ & $\arctan2(\frac{-k_{\phi}}{\cos C},\sqrt{h_{\phi}^{2}-k_{\phi}^{2}\tan^{2}C+l_{\phi}^{2}})$ & $\arctan2(-h_{\phi}\cos C\cos\chi+l_{\phi}\sin C,-l_{\phi}\cos C\cos\chi-h_{\phi}\sin C)$\tabularnewline
    $\theta+C$ & $\arctan2(\frac{k_{\phi}}{\cos C},-\sqrt{h_{\phi}^{2}-k_{\phi}^{2}\tan^{2}C+l_{\phi}^{2}})$ & $\arctan2(h_{\phi}\cos C\cos\chi-l_{\phi}\sin C,l_{\phi}\cos C\cos\chi+h_{\phi}\sin C)$\tabularnewline
    $\theta+C$ & $\arctan2(\frac{k_{\phi}}{\cos C},\sqrt{h_{\phi}^{2}-k_{\phi}^{2}\tan^{2}C+l_{\phi}^{2}})$ & $\arctan2(h_{\phi}\cos C\cos\chi-l_{\phi}\sin C,l_{\phi}\cos C\cos\chi+h_{\phi}\sin C)$\tabularnewline
\end{tabular}$$

$$\begin{tabular}{c}
 $2\theta$\tabularnewline
 \hline
 $2\arcsin-\frac{\sqrt{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}}{2k_{i}}$\tabularnewline
 $2\arcsin-\frac{\sqrt{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}}{2k_{i}}$\tabularnewline
 $2\arcsin\frac{\sqrt{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}}{2k_{i}}$\tabularnewline
 $2\arcsin\frac{\sqrt{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}}{2k_{i}}$\tabularnewline
\end{tabular}$$

où

*** Mode omega constant

Dans ce mode on choisit de garder $\omega$ toujours constant:

$$\omega=C$$

Le système s'écrit alors comme suit:

$$\begin{eqnarray*}
    h_{\phi} & = & 2k_{i}\sin\theta\left(\cos(C-\theta)\cos\chi\sin\phi+\sin(C-\theta)\cos\phi\right)\\
    k_{\phi} & = & 2k_{i}\sin\theta\cos(C-\theta)\sin\chi\\
    l_{\phi} & = & 2k_{i}\sin\theta\left(\cos(C-\theta)\cos\chi\cos\phi-\sin(C-\theta)\sin\phi\right)
\end{eqnarray*}$$

La résolution donne 4 quadruplets de solutions:

$$\begin{tabular}{ccc}
    $\omega$ & $\chi$ & $\phi$\tabularnewline
    \hline
    $-\theta+C$ & $\arctan2\left(-k_{\phi},-\sqrt{(h_{\phi}^{2}+l_{\phi}^{2})\cos^{2}(C-\theta)-k_{\phi}^{2}\sin^{2}(C-\theta)}\right)$ & $\arctan2(-h_{\phi}\cos C\cos\chi+l_{\phi}\sin C,-l_{\phi}\cos C\cos\chi-h_{\phi}\sin C)$\tabularnewline
    $-\theta+C$ & $\arctan2\left(-k_{\phi},\sqrt{(h_{\phi}^{2}+l_{\phi}^{2})\cos^{2}(C-\theta)-k_{\phi}^{2}\sin^{2}(C-\theta)}\right)$ & $\arctan2(-h_{\phi}\cos C\cos\chi+l_{\phi}\sin C,-l_{\phi}\cos C\cos\chi-h_{\phi}\sin C)$\tabularnewline
    $\theta+C$ & $\arctan2\left(k_{\phi},-\sqrt{(h_{\phi}^{2}+l_{\phi}^{2})\cos^{2}(C-\theta)-k_{\phi}^{2}\sin^{2}(C-\theta)}\right)$ & $\arctan2(h_{\phi}\cos C\cos\chi-l_{\phi}\sin C,l_{\phi}\cos C\cos\chi+h_{\phi}\sin C)$\tabularnewline
    $\theta+C$ & $\arctan2\left(k_{\phi},\sqrt{(h_{\phi}^{2}+l_{\phi}^{2})\cos^{2}(C-\theta)-k_{\phi}^{2}\sin^{2}(C-\theta)}\right)$ & $\arctan2(h_{\phi}\cos C\cos\chi-l_{\phi}\sin C,l_{\phi}\cos C\cos\chi+h_{\phi}\sin C)$\tabularnewline
\end{tabular}$$

$$\begin{tabular}{c}
    $2\theta$\tabularnewline
    \hline
    $2\arcsin-\frac{\sqrt{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}}{2k_{i}}$\tabularnewline
    $2\arcsin-\frac{\sqrt{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}}{2k_{i}}$\tabularnewline
    $2\arcsin\frac{\sqrt{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}}{2k_{i}}$\tabularnewline
    $2\arcsin\frac{\sqrt{h_{\phi}^{2}+k_{\phi}^{2}+l_{\phi}^{2}}}{2k_{i}}$\tabularnewline
\end{tabular}$$
* PseudoAxes

This section describe the calculations done by the library for the
different kind of pseudo axes.

** Eulerians to Kappa angles

1st solution

$$\begin{eqnarray*}
 \kappa_\omega & = & \omega - p + \frac{\pi}{2} \\
 \kappa & = & 2 \arcsin\left(\frac{\sin\frac{\chi}{2}}{\sin\alpha}\right) \\
 \kappa_\phi & = &  \phi - p - \frac{\pi}{2}
\end{eqnarray*}$$

or 2nd one

$$\begin{eqnarray*}
 \kappa_\omega & = & \omega - p - \frac{\pi}{2} \\
 \kappa & = & -2 \arcsin\left(\frac{\sin\frac{\chi}{2}}{\sin\alpha}\right) \\
 \kappa_\phi & = &  \phi - p + \frac{\pi}{2}
\end{eqnarray*}$$

where

$$p = \arcsin\left(\frac{\tan\frac{\chi}{2}}{\tan\alpha}\right);$$

and $\alpha$ is the angle of the kappa axis with the $\vec{y}$ axis.

** Kappa to Eulerians angles

1st solution

$$\begin{eqnarray*}
 \omega & = & \kappa_\omega + p - \frac{\pi}{2} \\
 \chi   & = & 2 \arcsin\left(\sin\frac{\kappa}{2} \sin\alpha\right) \\
 \phi   & = & \kappa_\phi + p + \frac{\pi}{2}
\end{eqnarray*}$$

or 2nd one

$$\begin{eqnarray*}
 \omega & = & \kappa_\omega + p + \frac{\pi}{2} \\
 \chi   & = & -2 \arcsin\left(\sin\frac{\kappa}{2} \sin\alpha\right) \\
 \phi   & = & \kappa_\phi + p - \frac{\pi}{2}
\end{eqnarray*}$$

where

$$p = \arctan\left(\tan\frac{\kappa}{2} \cos\alpha\right)$$

#+CAPTION: $\omega = 0$, $\chi = 0$, $\phi = 0$, 1st solution

[[../../figures/e2k_1.png]]
#+CAPTION: $\omega = 0$, $\chi = 0$, $\phi = 0$, 2nd solution

[[../../figures/e2k_2.png]]
#+CAPTION: $\omega = 0$, $\chi = 90$, $\phi = 0$, 1st solution

[[../../figures/e2k_3.png]]
#+CAPTION: $\omega = 0$, $\chi = 90$, $\phi = 0$, 2nd solution

[[../../figures/e2k_4.png]]
** Qper and Qpar

[[../../figures/qper_qpar.png]]
this pseudo axis engine compute the perpendicular
($\left|\left|\vec{Q_\text{per}}\right|\right|$) and parallel
($\left|\left|\vec{Q_\text{par}}\right|\right|$) contribution of
$\vec{Q}$ relatively to the surface of the sample defined by the
$\vec{n}$ vector.

$$\begin{eqnarray*}
\vec{q} & = & \vec{k_\text{f}} - \vec{k_\text{i}} \\
\vec{q} & = & \vec{q_\text{per}} + \vec{q_\text{par}} \\
\vec{q_\text{per}} & = & \frac{\vec{q} \cdot \vec{n}}{\left|\left|\vec{n}\right|\right|} \frac{\vec{n}}{\left|\left|\vec{n}\right|\right|}
\end{eqnarray*}$$
* Les Diffractomètres
** Eulérien 3S+1D

Nous allons nous inspirer du modèle de Busin et Levy pour décrire notre
diffractomètre. Les sens de rotation sont respectés mais le repère
directe est choisi de façon à correspondre au repère de laboratoire de
la ligne CRYSTAL du synchrotron Soleil. Les photons-X se propagent
suivant le vecteur $\vec{x}$ et la direction verticale est suivant le
vecteur $\vec{z}$. Ce diffractomètre est de type verticale (le vecteur
de diffusion $\vec{Q}$ est dans le plan xOz). Les angles permettant de
décrire la configuration du diffractomètre sont présentés sur la
figure~ref{[[cap:3S+1D]]}.

#+CAPTION: Dénomination des angles du diffractomètre 3S+1D
Eulérien.label{[[cap:3S+1D]]}

[[../../figures/3S+1D.png]]
** Eulérien 4S+2D

Nous allons nous inspirer du modèle de You pour notre diffractomètre
(fig.~ref{[[cap:4S+2D]]}) ici présenté tous les angles mis à zéro. Les
rayons-X arrivent suivant le vecteur $vec{x}$ (le repère est différent
de celui de You).

#+CAPTION: Dénomination des angles du diffractomètre 4S+2D
Eulérien.label{[[cap:4S+2D]]}

[[../../figures/4S+2D.png]]
Le principe des calcules de You est d'exprimer dans le repère du
laboratoire le vecteur diffusion $\vec{Q}$ de deux façons différentes.
Une première en utilisant les angles du goniomètre 4S puis une à partir
des angles du détecteur 2D et de la connaissance des coordonnées du
vecteur incident. En égalant les deux expressions, il obtient un système
d'équation à 6 inconnus mais seulement 3 équations. Pour être à même de
résoudre le système il faut fixer des contraintes supplémentaire. C'est
ce que l'on appel les modes de fonctionnement du diffractomètre. Il est
commode de définir d'autres angles que ceux du diffractomètre
relativement à des vecteurs caractéristiques tel que le vecteur de
diffusion $\vec{Q}$ ou un vecteur pointant dans une direction
particulière du cristal $\vec{n}$. Cette direction peut-être soit lié à
la cristallographie du cristal soit à sa forme (une normale à une face).
La figure~ref{[[cap:Pseudo-Angles-li=0000E9s]]} représente les angles
liés au vecteur de diffusion et à ce vecteur de référence. Tout d'abord
$\theta$ (angle entre $\vec{Q}$ et le plan $yz$) et qui correspond à
l'angle de Bragg. $\vartheta$ qui est l'angle azimutal que fait la
projection de $\vec{Q}$ sur le plan $yz$ et la direction $+y$
(fig~ref{[[cap:Pseudo-Angles-li=0000E9s}a]]). Il y a ensuite les angles
$\alpha$ et $\varphi$ définits comme précédemment mais pour le vecteur
de référence $\vec{n}$ (fig~ref{[[cap:Pseudo-Angles-li=0000E9s}b]]). Et
finalement les angles $tau$ (angle entre $\vec{Q}$ et $\vec{n}$) et
$\psi$ qui correspond à la rotation de $\vec{n}$ autour du vecteur de
diffusion $\vec{Q}$ (fig~ref{[[cap:Pseudo-Angles-li=0000E9s}c]]).
L'origine de cet angle $psi$ est prise à zéro lorsque le vecteur
$\vec{n}$ est dans le plan de diffraction (plan contenant $\vec{Q}$ et
$\vec{k_{i}}$) (fig~ref{[[cap:Pseudo-Angles-li=0000E9s}d]]).

#+CAPTION: Pseudo angles $\theta$ et $\vartheta$ liés à $\vec{Q}$

[[../../figures/4S+2D_reciprocal.png]]
#+CAPTION: Pseudo angles $\alpha$ et $\phi$ liés à $\vec{n}$

[[../../figures/4S+2D_reciprocal2.png]]
#+CAPTION: Pseudo angles $\tau$ et $\psi$ liés à $\vec{n}$ relativement
à $\vec{Q}$ et le plan de diffraction

[[../../figures/4S+2D_reciprocal3.png]]
#+CAPTION: Pseudo Angles liés au vecteur de diffusion $\vec{Q}$ et à
$\vec{n}$

[[../../figures/4S+2D_reciprocal4.png]]
Il est alors possible d'exprimer ces pseudos angles en fonction des
angles physique du diffractomètre.

** Eulerian 4 circles

#+CAPTION: Schematic view of the diffractometer.

[[../../../figures/3S+1D.png]]
*** Geometry

-  xrays source fix allong the $\vec{x}$ direction (1, 0, 0)
-  3 axes for the sample

   -  *omega* : rotating around the $-\vec{y}$ direction (0, -1, 0)
   -  *chi* : rotating around the $\vec{x}$ direction (1, 0, 0)
   -  *phi* : rotating around the $-\vec{y}$ direction (0, -1, 0)

-  1 axis for the detector

   -  *tth* : rotation around the $-\vec{y}$ direction (0, -1, 0)

*** Pseudo axes

**** hkl

PseudoAxes provided : *h*, *k* and *l*

-  mode *bissector*

   -  Axes: *omega*, *chi*, *phi*, *tth*
   -  Parameters : No parameter

   This mode add the bissector constrain =tth = 2 * omega=. In this mode
   the *chi* circle containt the vector of diffusion $\vec{Q}$. So it is
   easy to know the orientation of the hkl plan.

-  mode *constant\_omega*

   -  Axes : *chi*, *phi*, *tth*
   -  Parameters : No parameter

   This mode do not move the current *omega* axis.

-  mode *constant\_chi*

   -  Axes : *omega*, *phi*, *tth*
   -  Parameters : No parameter

   This mode do not move the current *chi* axis.

-  mode *constant\_phi*

   -  Axes related : *omega*, *chi*, *tth*
   -  Parameters : No parameter

   This mode do not move the current *phi* axis.

-  mode *double\_diffraction*

   -  Axes : *omega*, *chi*, *phi*, *tth*
   -  Parameters : *h2*, *k2*, *l2*

   This mode put a second hkl vector (*h2*, *k2*, *l2*) in Bragg
   condition. This is usefull sometimes when you want to explore two
   bragg peaks without moving your sample.

-  mode *psi\_constant*

   -  Axes : *omega*, *chi*, *phi*, *tth*
   -  Parameters : *h2*, *k2*, *l2*, *psi*

   This mode allow to fix the value of the pseudo axis *psi* at a
   constant value when you move around an *h*, *k* , *l* position. The
   (*h2*, *k2*, *l2*) vector is used as a reference for the computation
   of the *psi* pseudo axis value.

   You can retrive and =freeze= the current value of the *psi* pseudo
   axis value into the *psi* parameter when you initialize the mode. But
   you can also write directly the value of the desired *psi* parameter.

**** psi

PseudoAxis provided : *psi*

-  mode *psi*

   -  Axes : *omega*, *chi*, *phi*, *tth*
   -  Parameters : *h1*, *k1*, *l1*

**** q

PseudoAxis provided : *q*

where *q* is $|\vec{Q}| = \frac{2 \tau}{\lambda} \sin{\theta}$

-  mode : *q*

   -  Axes : *"tth"*
   -  Parameters : no parameter

** Eulerian 6 circles

#+CAPTION: Schematic view of the diffractometer.

[[../../../figures/4S+2D.png]]
*** Geometry

-  xrays source fix allong the $\vec{x}$ direction (1, 0, 0)
-  4 axes for the sample

   -  *mu* : rotating around the $\vec{z}$ direction (0, 0, 1)
   -  *omega* : rotating around the $-\vec{y}$ direction (0, -1, 0)
   -  *chi* : rotating around the $\vec{x}$ direction (1, 0, 0)
   -  *phi* : rotating around the $-\vec{y}$ direction (0, -1, 0)

-  2 axes for the detector

   -  *gamma* : rotation around the $\vec{z}$ direction (0, 0, 1)
   -  *delta* : rotation around the $-\vec{y}$ direction (0, -1, 0)

*** PseudoAxes

**** hkl

PseudoAxes provided : *h*, *k* and *l*

-  mode *bissector\_vertical*

   -  Axes: *omega*, *chi*, *phi*, *delta*
   -  Parameters : No parameter

   This mode add the bissector constrain =delta = 2 * omega=. In this
   mode the *chi* circle containt the vector of diffusion $\vec{Q}$. So
   it is easy to know the orientation of the hkl plan.

-  mode *constant\_omega\_vertical*

   -  Axes: *"chi"*, *"phi"*, *"delta"*
   -  Parameters : no parameter

   This mode do not move the *omega* axis.

-  mode *constant\_chi\_vertical*

   -  Axes: *"omega"*, *"phi"*, *"delta"*
   -  Parameters : no parameter

   This mode do not move the *chi* axis.

-  mode *constant\_phi\_vertical*

   -  Axes : *"omega"*, *"chi"*, *"delta"*
   -  Parameters : no parameter

   This mode do not move the *phi* axis.

-  mode : *lifting\_detector\_phi*

   -  Axes : *"phi"*, *"gamma"*, *"delta"*
   -  Parameters : No Parameters

-  mode : *lifting\_detector\_omega*

   -  Axes : *"omega"*, *"gamma"*, *"delta"*
   -  Parameters : No Parameters

-  mode : *lifting\_detector\_mu*

   -  Axes : *"mu"*, *"gamma"*, *"delta"*
   -  Parameters : No Parameters

-  mode : *double\_diffraction vertical*

   -  Axes : *"omega"*, *"chi"*, *"phi"*, *"delta"*
   -  Parameters : *h2*, *k2*, *l2*

   This mode put a second hkl vector (*h2*, *k2*, *l2*) in Bragg
   condition. This is usefull sometimes when you want to explore two
   bragg peaks without moving your sample.

-  mode : *bissector\_horizontal*

   -  Axes : *"mu"*, *"omega"*, *"chi"*, *"phi"*, *"gamma"*
   -  Parameters : No parameters

-  mode : *double\_diffraction\_horizontal*

   -  Axes : *"mu"*, *"omega"*, *"chi"*, *phi*, *"gamma"*
   -  Parameters : *h2*, *k2*, *l2*

   This mode put a second hkl vector (*h2*, *k2*, *l2*) in Bragg
   condition. This is usefull sometimes when you want to explore two
   bragg peaks without moving your sample.

-  mode : *psi\_constant\_vertical*

   -  Axes : *"omega"*, *"chi"*, *phi*, *"delta"*
   -  Parameters : *h2*, *k2*, *l2*, *psi*

   This mode allow to fix the value of the pseudo axis *psi* at a
   constant value when you move around an *h*, *k* , *l* position. The
   (*h2*, *k2*, *l2*) vector is used as a reference for the computation
   of the *psi* pseudo axis value.

   You can retrive and =freeze= the current value of the *psi* pseudo
   axis value into the *psi* parameter when you initialize the mode. But
   you can also write directly the value of the desired *psi* parameter.

-  mode : *psi\_constant\_horizontal*

   -  Axes : *"omega"*, *"chi"*, *phi*, *"gamma"*
   -  Parameters : *h2*, *k2*, *l2*, *psi*

   This mode allow to fix the value of the pseudo axis *psi* at a
   constant value when you move around an *h*, *k* , *l* position. The
   (*h2*, *k2*, *l2*) vector is used as a reference for the computation
   of the *psi* pseudo axis value.

   You can retrive and =freeze= the current value of the *psi* pseudo
   axis value into the *psi* parameter when you initialize the mode. But
   you can also write directly the value of the desired *psi* parameter.

-  mode *constant\_mu\_horizontal*

   -  Axes : *"chi"*, *"phi"*, *"gamma"*
   -  Parameters : no parameter

   This mode do not move the *mu* axis.

**** psi

PseudoAxis provided : *psi*

-  mode *psi\_vertical*

   -  Axes : *komega*, *kappa*, *kphi*, *delta*
   -  Parameters : *h1*, *k1*, *l1*

   The (*h1*, *k1*, *l1*) vector is used as a reference for the
   computation of the *psi* pseudo axis value.

**** q2

PseudoAxis provided : *q*, *alpha*

where *q* is $|\vec{Q}| = \frac{2 \tau}{\lambda} \sin{\theta}$ and
*alpha* is the azimuth of $\vec{Q}$ in the =yz= plan. The origin of this
angles is the $\vec{y}$ vector, and the positive rotation along
$\vec{x}$

-  mode : *q2*

   -  Axes : *"gamma"*, *"delta"*
   -  Parameters : no parameter

** Kappa 4 circles vertical

#+CAPTION: Schematic view of the diffractometer.

[[../../../figures/k4cv.png]]
*** Geometry

For this geometry there is a special parameters called $\alpha$ which is
the angle between the kappa rotation axis and the $\vec{y}$ direction.

-  xrays source fix allong the $\vec{x}$ direction (1, 0, 0)
-  3 axes for the sample

   -  *komega* : rotating around the $-\vec{y}$ direction (0, -1, 0)
   -  *kappa* : rotating around the $\vec{x}$ direction (0,
      $-\cos\alpha$, $-\sin\alpha$)
   -  *kphi* : rotating around the $-\vec{y}$ direction (0, -1, 0)

-  1 axis for the detector

   -  *tth* : rotation around the $-\vec{y}$ direction (0, -1, 0)

*** PseudoAxes

**** eulerians

PseudoAxes provides : *"omega"*, *"chi"*, *"phi"*

-  mode *eulerians*

   -  Axes : *komega*, *kappa*, *kphi*
   -  Parameters : *"solution"*

   When you compute the eulerians values from the kappa axes values,
   there is two possibilities, so the *"solution"* parameter when set 0
   or 1 allow to switch from one solution to the other.

**** hkl

PseudoAxes provided : *h*, *k* and *l*

-  mode *bissector*

   -  Axes: *komega*, *kappa*, *kphi*, *tth*
   -  Parameters : No parameter

   This mode add the bissector constrain =tth = 2 * omega=. In this mode
   the equivalent eulerian *chi* circle containt the vector of diffusion
   $\vec{Q}$. So it is easy to know the orientation of the hkl plan.

-  mode *constant\_omega*

   -  Axes : *"komega"*, *"kappa"*, *"kphi"*, *"tth"*
   -  Parameters : *"omega"*

   This mode do not move the equivalent eulerian *omega* axis, fixed by
   the parameter of the mode.

-  mode *constant\_chi*

   -  Axes : *"komega"*, *"kappa"*, *"kphi"*, *"tth"*
   -  Parameters : *"chi"*

   This mode do not move the equivalent eulerian *chi* axis fixed by the
   parameter of the mode.

-  mode *constant\_phi*

   -  Axes related : *"komega"*, *"kappa"*, *"kphi"*, *"tth"*
   -  Parameters : *"phi"*

   This mode do not move the equivalent eulerian *phi* axis fixed by the
   parameter of the mode.

-  mode *double\_diffraction*

   -  Axes : *komega*, *kappa*, *kphi*, *tth*
   -  Parameters : *h2*, *k2*, *l2*

   This mode put a second hkl vector (*h2*, *k2*, *l2*) in Bragg
   condition. This is usefull sometimes when you want to explore two
   bragg peaks without moving your sample.

-  mode *psi\_constant*

   -  Axes : *komega*, *kappa*, *kphi*, *tth*
   -  Parameters : *h2*, *k2*, *l2*, *psi*

   This mode allow to fix the value of the pseudo axis *psi* at a
   constant value when you move around an *h*, *k* , *l* position. The
   (*h2*, *k2*, *l2*) vector is used as a reference for the computation
   of the *psi* pseudo axis value.

   You can retrive and =freeze= the current value of the *psi* pseudo
   axis value into the *psi* parameter when you initialize the mode. But
   you can also write directly the value of the desired *psi* parameter.

**** psi

PseudoAxis provided : *psi*

-  mode *psi*

   -  Axes : *komega*, *kappa*, *kphi*, *tth*
   -  Parameters : *h1*, *k1*, *l1*

**** q

PseudoAxis provided : *q*

where *q* is $|\vec{Q}| = \frac{2 \tau}{\lambda} \sin{\theta}$

-  mode : *q*

   -  Axes : *"tth"*
   -  Parameters : no parameter

** Kappa 6 circles

#+CAPTION: Schematic view of the diffractometer.

[[../../../figures/k6c.png]]
*** Geometry

For this geometry there is a special parameters called $\alpha$ which is
the angle between the kappa rotation axis and the $\vec{y}$ direction.

-  xrays source fix allong the $\vec{x}$ direction (1, 0, 0)
-  4 axes for the sample

   -  *mu* : rotating around the $\vec{z}$ direction (0, 0, 1)
   -  *komega* : rotating around the $-\vec{y}$ direction (0, -1, 0)
   -  *kappa* : rotating around the $\vec{x}$ direction (0,
      $-\cos\alpha$, $-\sin\alpha$)
   -  *kphi* : rotating around the $-\vec{y}$ direction (0, -1, 0)

-  2 axes for the detector

   -  *gamma* : rotation around the $\vec{z}$ direction (0, 0, 1)
   -  *delta* : rotation around the $-\vec{y}$ direction (0, -1, 0)

*** PseudoAxes

**** eulerians

PseudoAxes provides : *"omega"*, *"chi"*, *"phi"*

-  mode *eulerians*

   -  Axes : *komega*, *kappa*, *kphi*
   -  Parameters : *"solution"*

   When you compute the eulerians values from the kappa axes values,
   there is two possibilities, so the *"solution"* parameter when set 0
   or 1 allow to switch from one solution to the other.

**** hkl

PseudoAxes provided : *h*, *k* and *l*

-  mode *bissector\_vertical*

   -  Axes: *komega*, *kappa*, *kphi*, *delta*
   -  Parameters : No parameter

   This mode add the bissector constrain =tth = 2 * omega=. In this mode
   the equivalent eulerian *chi* circle containt the vector of diffusion
   $\vec{Q}$. So it is easy to know the orientation of the hkl plan.

-  mode *constant\_omega\_vertical*

   -  Axes: *"komega"*, *"kappa"*, *"kphi"*, *"delta"*
   -  Parameters : *omega*

   This mode do not move the equivalent eulerian *omega* axis.

-  mode *constant\_chi\_vertical*

   -  Axes: *"komega"*, *"kappa"*, *"kphi"*, *"delta"*
   -  Parameters : *chi*

   This mode do not move the equivalent eulerian *chi* axis.

-  mode *constant\_phi\_vertical*

   -  Axes : *"komega"*, *"kappa"*, *"kphi"*, *"delta"*
   -  Parameters : *phi*

   This mode do not move the equivalent eulerian *phi* axis.

-  mode : *lifting\_detector\_kphi*

   -  Axes : *"kphi"*, *"gamma"*, *"delta"*
   -  Parameters : No Parameters

-  mode : *lifting\_detector\_mu*

   -  Axes : *"mu"*, *"gamma"*, *"delta"*
   -  Parameters : No Parameters

-  mode : *double\_diffraction vertical*

   -  Axes : *"komega"*, *"kappa"*, *"kphi"*, *"delta"*
   -  Parameters : *h2*, *k2*, *l2*

   This mode put a second hkl vector (*h2*, *k2*, *l2*) in Bragg
   condition. This is usefull sometimes when you want to explore two
   bragg peaks without moving your sample.

-  mode : *bissector\_horizontal*

   -  Axes : *"mu"*, *"komega"*, *"kappa"*, *"kphi"*, *"gamma"*
   -  Parameters : No parameters

-  mode : *constant\_phi\_horizontal*

   -  Axes : *"mu"*, *"komega"*, *"kappa"*, *"kphi"*, *"gamma"*
   -  Parameters : *phi*

-  mode : *horizontal kphi constant*

   -  Axes : *"mu"*, *"komega"*, *"kappa"*, *"gamma"*
   -  Parameters : no parameters

-  mode : *double\_diffraction\_horizontal*

   -  Axes : *"mu"*, *"komega"*, *"kappa"*, *kphi*, *"gamma"*
   -  Parameters : *h2*, *k2*, *l2*

   This mode put a second hkl vector (*h2*, *k2*, *l2*) in Bragg
   condition. This is usefull sometimes when you want to explore two
   bragg peaks without moving your sample.

-  mode : *psi\_constant\_vertical*

   -  Axes : *"komega"*, *"kappa"*, *kphi*, *"delta"*
   -  Parameters : *h2*, *k2*, *l2*, *psi*

   This mode allow to fix the value of the pseudo axis *psi* at a
   constant value when you move around an *h*, *k* , *l* position. The
   (*h2*, *k2*, *l2*) vector is used as a reference for the computation
   of the *psi* pseudo axis value.

   You can retrive and =freeze= the current value of the *psi* pseudo
   axis value into the *psi* parameter when you initialize the mode. But
   you can also write directly the value of the desired *psi* parameter.

-  mode : *constant\_incidence*

   -  Axes : *"komega"*, *"kappa"*, *kphi*, *"gamma"*, *"delta"*
   -  Parameters : *x*, *y*, *z*, *incidence*, *azimuth*

   This mode allow to work with a constant incidence of the incoming
   beam onto the sample surface. To use this mode you need to follow a
   few steps:

   #+BEGIN_QUOTE

     -  align your surface along a direction $\vec{n}$ (*x*, *y*, *z*)
        in the laboratory space, with your diffractometer.
     -  initialize the mode, so it can remember the current
        diffractometer position for futur computation.
     -  set the desired *incidence*
     -  set the desired *azimuth* of the normal of the surface in the
        YOZ plane (azimuth = 0 -> $\vec{n}$ along $\vec{y}$)
   #+END_QUOTE

   Now it is possible to do an HKL computation.

**** psi

PseudoAxis provided : *psi*

-  mode *psi\_vertical*

   -  Axes : *komega*, *kappa*, *kphi*, *delta*
   -  Parameters : *h1*, *k1*, *l1*

   The (*h1*, *k1*, *l1*) vector is used as a reference for the
   computation of the *psi* pseudo axis value.

**** q2

PseudoAxis provided : *q*, *alpha*

where *q* is $|\vec{Q}| = \frac{2 \tau}{\lambda} \sin{\theta}$ and
*alpha* is the azimuth of $\vec{Q}$ in the =yz= plan. The origin of this
angles is the $\vec{y}$ vector, and the positive rotation along
$\vec{x}$

-  mode : *q2*

   -  Axes : *"gamma"*, *"delta"*
   -  Parameters : no parameter

** SOLEIL MARS

*** Geometry

-  xrays source fix allong the $\vec{x}$ direction (1, 0, 0)
-  3 axes for the sample

   -  *omega* : rotating around the $\vec{z}$ direction (0, -1, 0)
   -  *chi* : rotating around the $\vec{x}$ direction (-1, 0, 0)
   -  *phi* : rotating around the $\vec{z}$ direction (0, 0, 1)

-  1 axis for the detector

   -  *tth* : rotation around the $\vec{z}$ direction (0, -1, 0)

*** Pseudo axes

**** hkl

PseudoAxes provided : *h*, *k* and *l*

-  mode *bissector*

   -  Axes: *omega*, *chi*, *phi*, *tth*
   -  Parameters : No parameter

   This mode add the bissector constrain =tth = 2 * omega=. In this mode
   the *chi* circle containt the vector of diffusion $\vec{Q}$. So it is
   easy to know the orientation of the hkl plan.

-  mode *constant\_omega*

   -  Axes : *chi*, *phi*, *tth*
   -  Parameters : No parameter

   This mode do not move the current *omega* axis.

-  mode *constant\_chi*

   -  Axes : *omega*, *phi*, *tth*
   -  Parameters : No parameter

   This mode do not move the current *chi* axis.

-  mode *constant\_phi*

   -  Axes related : *omega*, *chi*, *tth*
   -  Parameters : No parameter

   This mode do not move the current *phi* axis.

-  mode *double\_diffraction*

   -  Axes : *omega*, *chi*, *phi*, *tth*
   -  Parameters : *h2*, *k2*, *l2*

   This mode put a second hkl vector (*h2*, *k2*, *l2*) in Bragg
   condition. This is usefull sometimes when you want to explore two
   bragg peaks without moving your sample.

-  mode *psi\_constant*

   -  Axes : *omega*, *chi*, *phi*, *tth*
   -  Parameters : *h2*, *k2*, *l2*, *psi*

   This mode allow to fix the value of the pseudo axis *psi* at a
   constant value when you move around an *h*, *k* , *l* position. The
   (*h2*, *k2*, *l2*) vector is used as a reference for the computation
   of the *psi* pseudo axis value.

   You can retrive and =freeze= the current value of the *psi* pseudo
   axis value into the *psi* parameter when you initialize the mode. But
   you can also write directly the value of the desired *psi* parameter.

**** psi

PseudoAxis provided : *psi*

-  mode *psi*

   -  Axes : *omega*, *chi*, *phi*, *tth*
   -  Parameters : *h1*, *k1*, *l1*

**** q

PseudoAxis provided : *q*

where *q* is $|\vec{Q}| = \frac{2 \tau}{\lambda} \sin{\theta}$

-  mode : *q*

   -  Axes : *"tth"*
   -  Parameters : no parameter

** SOLEIL SIXS MED1+2

*** Geometry

-  xrays source fix allong the $\vec{x}$ direction (1, 0, 0)
-  2 axes for the sample

   -  *pitch* : rotation around the $-\vec{y}$ direction (0, -1, 0)
   -  *mu* : rotation around the $\vec{z}$ direction (0, 0, 1)

-  3 axis for the detector

   -  *pitch* : rotation around the $-\vec{y}$ direction (0, -1, 0)
   -  *gamma* : rotation around the $\vec{z}$ direction (0, 0, 1)
   -  *delta* : rotation around the $-\vec{y}$ direction (0, -1, 0)

*** PseudoAxes

**** hkl

PseudoAxes provided : *h*, *k* and *l*

-  mode *pitch\_fixed*

   -  Axes : *mu*, *gamma*, *delta*
   -  Parameters : No parameter

**** q2

PseudoAxis provided : *q*, *alpha*

where *q* is $|\vec{Q}| = \frac{2 \tau}{\lambda} \sin{\theta}$ and
*alpha* is the azimuth of $\vec{Q}$ in the =yz= plan. The origin of this
angles is the $\vec{y}$ vector, and the positive rotation along
$\vec{x}$

-  mode : *q2*

   -  Axes : *"gamma"*, *"delta"*
   -  Parameters : no parameter

** SOLEIL SIXS MED2+2

*** Geometry

-  xrays source fix allong the $\vec{x}$ direction (1, 0, 0)
-  3 axes for the sample

   -  *beta* : rotation around the $-\vec{y}$ direction (0, -1, 0)
   -  *mu* : rotation around the $\vec{z}$ direction (0, 0, 1)
   -  *omega* : rotating around the $-\vec{y}$ direction (0, -1, 0)

-  3 axis for the detector

   -  *beta* : rotation around the $-\vec{y}$ direction (0, -1, 0)
   -  *gamma* : rotation around the $\vec{z}$ direction (0, 0, 1)
   -  *delta* : rotation around the $-\vec{y}$ direction (0, -1, 0)

*** PseudoAxes

**** hkl

PseudoAxes provided : *h*, *k* and *l*

-  mode *mu\_fixed*

   -  Axes : *omega*, *gamma*, *delta*
   -  Parameters : No parameter

-  mode *reflectivity*

   -  Axes : *mu*, *omega*, *gamma*, *delta*
   -  Parameters : No parameter

   This mode add the reflectivity constraint =2*mu = gamma=. The
   incomming beam angle and the outgoing beam angle are equals.

**** q2

PseudoAxis provided : *q*, *alpha*

where *q* is $|\vec{Q}| = \frac{2 \tau}{\lambda} \sin{\theta}$ and
*alpha* is the azimuth of $\vec{Q}$ in the =yz= plan. The origin of this
angles is the $\vec{y}$ vector, and the positive rotation along
$\vec{x}$

-  mode : *q2*

   -  Axes : *"gamma"*, *"delta"*
   -  Parameters : no parameter

** SOLEIL SIXS MED2+3

*** Geometry

-  xrays source fix allong the $\vec{x}$ direction (1, 0, 0)
-  3 axes for the sample

   -  *beta* : rotation around the $-\vec{y}$ direction (0, -1, 0)
   -  *mu* : rotation around the $\vec{z}$ direction (0, 0, 1)
   -  *omega* : rotating around the $-\vec{y}$ direction (0, -1, 0)

-  3 axis for the detector

   -  *beta* : rotation around the $-\vec{y}$ direction (0, -1, 0)
   -  *gamma* : rotation around the $\vec{z}$ direction (0, 0, 1)
   -  *delta* : rotation around the $-\vec{y}$ direction (0, -1, 0)
   -  *eta\_a* : rotation around the $-\vec{x}$ direction (-1, 0, 0)

*** PseudoAxes

**** hkl

PseudoAxes provided : *h*, *k* and *l*

-  mode *mu\_eta\_a\_fixed*

   -  Axes : *omega*, *gamma*, *delta*
   -  Parameters : No parameter

-  mode *mu\_fixed*

   -  Axes : *mu*, *omega*, *gamma*, *eta\_a*
   -  Parameters : No parameter

   This mode add the slits constant orientation compare to the surface
   of the sample, which is along the *omega* axis.

**** q2

PseudoAxis provided : *q*, *alpha*

where *q* is $|\vec{Q}| = \frac{2 \tau}{\lambda} \sin{\theta}$ and
*alpha* is the azimuth of $\vec{Q}$ in the =yz= plan. The origin of this
angles is the $\vec{y}$ vector, and the positive rotation along
$\vec{x}$

-  mode : *q2*

   -  Axes : *"gamma"*, *"delta"*
   -  Parameters : no parameter

**** qper\_qpar

PseudoAxis provided : *qper*, *qpar*

where *qper* and *qpar* are the perpendicular and parallel composants of
the $|\vec{Q}|$ vector. projected respectively to the surface vector of
the sample.
** PETRA3 P09 EH2

*** Geometry

-  xrays source fix allong the $\vec{x}$ direction (1, 0, 0)
-  4 axes for the sample

   -  *mu* : rotation around the $-\vec{y}$ direction (0, -1, 0)
   -  *omega* : rotation around the $\vec{z}$ direction (0, 0, 1)
   -  *chi* : rotating around the $\vec{x}$ direction (1, 0, 0)
   -  *phi* : rotating around the $\vec{z}$ direction (0, 0, 1)

-  3 axis for the detector

   -  *mu* : rotation around the $-\vec{y}$ direction (0, -1, 0)
   -  *delta* : rotation around the $\vec{z}$ direction (0, 0, 1)
   -  *gamma* : rotation around the $-\vec{y}$ direction (0, -1, 0)

*** PseudoAxes

**** hkl

PseudoAxes provided : *h*, *k* and *l*

-  mode *zaxis + alpha-fixed*

   -  Axes : *"omega"*, *"gamma"*, *"delta"*
   -  Parameters : No parameter

-  mode *zaxis + beta-fixed*

   -  Axes : *"mu"*, *"omega"*, *"delta"*
   -  Parameters : No parameter

-  mode *zaxis + alpha=beta*

   -  Axes : *"mu"*, *"omega"*, *"gamma"*, *"delta"*
   -  Parameters : No parameter

   This mode add the =mu = gamma= constrain.

-  mode *4-circles bissector\_horizontal*

   -  Axes: *"omega"*, *"chi"*, *"phi"*, *"delta"*
   -  Parameters : No parameter

   This mode add the bissector constrain =delta = 2 * omega=. In this
   mode the eulerian *"chi"* circle containt the vector of diffusion
   $\vec{Q}$. So it is easy to know the orientation of the hkl plan.

-  mode *4-circles constant\_omega\_horizontal*

   -  Axes: *"chi"*, *"phi"*, *"delta"*
   -  Parameters : No parameter

   This mode do not move the *"omega"* axis.

-  mode *4-circles constant\_chi\_horizontal*

   -  Axes: *"omega"*, *"phi"*, *"delta"*
   -  Parameters : No parameter

   This mode do not move the *"chi"* axis.

-  mode *4-circles constant\_phi\_horizontal*

   -  Axes: *"omega"*, *"chi"*, *"delta"*
   -  Parameters : No parameter

   This mode do not move the *"phi"* axis.

** SOLEIL SIRIUS KAPPA

*** Geometry

For this geometry there is a special parameters called $\alpha$ which is
the angle between the kappa rotation axis and the $\vec{y}$ direction.

-  xrays source fix allong the $\vec{x}$ direction (1, 0, 0)
-  4 axes for the sample

   -  *mu* : rotating around the $-\vec{z}$ direction (0, 0, -1)
   -  *komega* : rotating around the $-\vec{y}$ direction (0, -1, 0)
   -  *kappa* : rotating around the $\vec{x}$ direction (0,
      $-\cos\alpha$, $-\sin\alpha$)
   -  *kphi* : rotating around the $-\vec{y}$ direction (0, -1, 0)

-  2 axes for the detector

   -  *delta* : rotation around the $-\vec{z}$ direction (0, 0, -1)
   -  *gamma* : rotation around the $-\vec{y}$ direction (0, -1, 0)

*** PseudoAxes

**** eulerians

PseudoAxes provides : *"omega"*, *"chi"*, *"phi"*

-  mode *eulerians*

   -  Axes : *komega*, *kappa*, *kphi*
   -  Parameters : *"solution"*

   When you compute the eulerians values from the kappa axes values,
   there is two possibilities, so the *"solution"* parameter when set 0
   or 1 allow to switch from one solution to the other.

**** hkl

PseudoAxes provided : *h*, *k* and *l*

-  mode *bissector\_vertical*

   -  Axes: *komega*, *kappa*, *kphi*, *delta*
   -  Parameters : No parameter

   This mode add the bissector constrain =tth = 2 * omega=. In this mode
   the equivalent eulerian *chi* circle containt the vector of diffusion
   $\vec{Q}$. So it is easy to know the orientation of the hkl plan.

-  mode *constant\_omega\_vertical*

   -  Axes: *"komega"*, *"kappa"*, *"kphi"*, *"delta"*
   -  Parameters : *omega*

   This mode do not move the equivalent eulerian *omega* axis.

-  mode *constant\_chi\_vertical*

   -  Axes: *"komega"*, *"kappa"*, *"kphi"*, *"delta"*
   -  Parameters : *chi*

   This mode do not move the equivalent eulerian *chi* axis.

-  mode *constant\_phi\_vertical*

   -  Axes : *"komega"*, *"kappa"*, *"kphi"*, *"delta"*
   -  Parameters : *phi*

   This mode do not move the equivalent eulerian *phi* axis.

-  mode : *lifting\_detector\_kphi*

   -  Axes : *"kphi"*, *"gamma"*, *"delta"*
   -  Parameters : No Parameters

-  mode : *lifting\_detector\_mu*

   -  Axes : *"mu"*, *"gamma"*, *"delta"*
   -  Parameters : No Parameters

-  mode : *double\_diffraction vertical*

   -  Axes : *"komega"*, *"kappa"*, *"kphi"*, *"delta"*
   -  Parameters : *h2*, *k2*, *l2*

   This mode put a second hkl vector (*h2*, *k2*, *l2*) in Bragg
   condition. This is usefull sometimes when you want to explore two
   bragg peaks without moving your sample.

-  mode : *bissector\_horizontal*

   -  Axes : *"mu"*, *"komega"*, *"kappa"*, *"kphi"*, *"gamma"*
   -  Parameters : No parameters

-  mode : *constant\_phi\_horizontal*

   -  Axes : *"mu"*, *"komega"*, *"kappa"*, *"kphi"*, *"gamma"*
   -  Parameters : *phi*

-  mode : *horizontal kphi constant*

   -  Axes : *"mu"*, *"komega"*, *"kappa"*, *"gamma"*
   -  Parameters : no parameters

-  mode : *double\_diffraction\_horizontal*

   -  Axes : *"mu"*, *"komega"*, *"kappa"*, *kphi*, *"gamma"*
   -  Parameters : *h2*, *k2*, *l2*

   This mode put a second hkl vector (*h2*, *k2*, *l2*) in Bragg
   condition. This is usefull sometimes when you want to explore two
   bragg peaks without moving your sample.

-  mode : *psi\_constant\_vertical*

   -  Axes : *"komega"*, *"kappa"*, *kphi*, *"delta"*
   -  Parameters : *h2*, *k2*, *l2*, *psi*

   This mode allow to fix the value of the pseudo axis *psi* at a
   constant value when you move around an *h*, *k* , *l* position. The
   (*h2*, *k2*, *l2*) vector is used as a reference for the computation
   of the *psi* pseudo axis value.

   You can retrive and =freeze= the current value of the *psi* pseudo
   axis value into the *psi* parameter when you initialize the mode. But
   you can also write directly the value of the desired *psi* parameter.

-  mode : *constant\_incidence*

   -  Axes : *"komega"*, *"kappa"*, *kphi*, *"gamma"*, *"delta"*
   -  Parameters : *x*, *y*, *z*, *incidence*, *azimuth*

   This mode allow to work with a constant incidence of the incoming
   beam onto the sample surface. To use this mode you need to follow a
   few steps:

   #+BEGIN_QUOTE

     -  align your surface along a direction $\vec{n}$ (*x*, *y*, *z*)
        in the laboratory space, with your diffractometer.
     -  initialize the mode, so it can remember the current
        diffractometer position for futur computation.
     -  set the desired *incidence*
     -  set the desired *azimuth* of the normal of the surface in the
        YOZ plane (azimuth = 0 -> $\vec{n}$ along $\vec{y}$)
   #+END_QUOTE

   Now it is possible to do an HKL computation.

**** psi

PseudoAxis provided : *psi*

-  mode *psi\_vertical*

   -  Axes : *komega*, *kappa*, *kphi*, *delta*
   -  Parameters : *h1*, *k1*, *l1*

   The (*h1*, *k1*, *l1*) vector is used as a reference for the
   computation of the *psi* pseudo axis value.

**** q2

PseudoAxis provided : *q*, *alpha*

where *q* is $|\vec{Q}| = \frac{2 \tau}{\lambda} \sin{\theta}$ and
*alpha* is the azimuth of $\vec{Q}$ in the =yz= plan. The origin of this
angles is the $\vec{y}$ vector, and the positive rotation along
$\vec{x}$

-  mode : *q2*

   -  Axes : *"gamma"*, *"delta"*
   -  Parameters : no parameter

** SOLEIL SIRIUS TURRET

*** Geometry

-  xrays source fix allong the $\vec{x}$ direction (1, 0, 0)
-  3 axes for the sample

   -  *thetah* : rotating around the $-\vec{z}$ direction (0, 0, -1)
   -  *alphay* : rotating around the $\vec{y}$ direction (0, 1, 0)
   -  *alphax* : rotating around the $\vec{x}$ direction (1, 0, 0)

-  2 axes for the detector

   -  *delta* : rotation around the $-\vec{z}$ direction (0, 0, -1)
   -  *gamma* : rotation around the $-\vec{y}$ direction (0, -1, 0)

*** PseudoAxes

**** hkl

PseudoAxes provided : *h*, *k* and *l*

-  mode : *lifting\_detector\_thetah*

   -  Axes : *"thetah"*, *"delta"*, *"gamma"*
   -  Parameters : No Parameters

**** q2

PseudoAxis provided : *q*, *alpha*

where *q* is $|\vec{Q}| = \frac{2 \tau}{\lambda} \sin{\theta}$ and
*alpha* is the azimuth of $\vec{Q}$ in the =yz= plan. The origin of this
angles is the $\vec{y}$ vector, and the positive rotation along
$\vec{x}$

-  mode : *q2*

   -  Axes : *"gamma"*, *"delta"*
   -  Parameters : no parameter

**** qper\_qpar

PseudoAxis provided : *qper*, *qpar*

where *qper* and *qpar* are the perpendicular and parallel composants of
the $|\vec{Q}|$ vector projected respectively to the surface vector
$\vec{n}$ of coordinates $x$, $y$, $z$ of the sample expressed in the
sample referential. The default value for $n$ is (0, 1, 0)

-  mode : *qper\_qpar*

   -  Axes : *"delta"*, *"gamma"*
   -  Parameters : *"x"*, *"y"*, *"z"*

** Z-Axis

*** Geometry

For this geometry the *mu* axis is common to the sample and the
detector.

-  xrays source fix allong the $\vec{x}$ direction (1, 0, 0)
-  2 axes for the sample

   -  *mu* : rotation around the $\vec{z}$ direction (0, 0, 1)
   -  *omega* : rotating around the $-\vec{y}$ direction (0, -1, 0)

-  3 axis for the detector

   -  *mu* : rotation around the $\vec{z}$ direction (0, 0, 1)
   -  *delta* : rotation around the $-\vec{y}$ direction (0, -1, 0)
   -  *gamma* : rotation around the $\vec{z}$ direction (0, 0, 1)

*** PseudoAxes

**** hkl

PseudoAxes provided : *h*, *k* and *l*

-  mode *zaxis*

   -  Axes : *omega*, *delta*, *gamma*
   -  Parameters : No parameter

-  mode *reflectivity*

   -  Axes : *mu*, *omega*, *delta*, *gamma*
   -  Parameters : No parameter

   This mode add the reflectivity constraint =mu = gamma=. The incomming
   beam angle and the outgoing beam angle are equals.

**** q2

PseudoAxis provided : *q*, *alpha*

where *q* is $|\vec{Q}| = \frac{2 \tau}{\lambda} \sin{\theta}$ and
*alpha* is the azimuth of $\vec{Q}$ in the =yz= plan. The origin of this
angles is the $\vec{y}$ vector, and the positive rotation along
$\vec{x}$

-  mode : *q2*

   -  Axes : *"gamma"*, *"delta"*
   -  Parameters : no parameter
* Developpement

** Getting hkl

To get hkl, you can download the last stable version from sourceforge or
if you want the latest development version use
[[http://git.or.cz/][git]] or
[[http://code.google.com/p/msysgit/downloads/list][msysgit]] on windows
system and do:

#+BEGIN_EXAMPLE
    $ git clone git://repo.or.cz/hkl.git
#+END_EXAMPLE

or:

#+BEGIN_EXAMPLE
    $ git clone http://repo.or.cz/r/hkl.git (slower)
#+END_EXAMPLE

then checkout the next branch like this:

#+BEGIN_EXAMPLE
    $ cd hkl
    $ git checkout -b next origin/next
#+END_EXAMPLE

** Building hkl

To build hkl you need [[http://www.python.org][Python 2.3+]] the
[[http://www.gnu.org/software/gsl/][GNU Scientific Library 1.12]] and
[[https://developer.gnome.org/glib/][GLib-2.0 >= 2.3.4]]:

#+BEGIN_EXAMPLE
    $ ./configure --disable-gui
    $ make
    $ sudo make install
#+END_EXAMPLE

you can also build a GUI interfaces which use
[[http://www.gtk.org][gtk]]:

#+BEGIN_EXAMPLE
    $ ./configure
    $ make
    $ sudo make install
#+END_EXAMPLE

optionnaly you can build an experimental /libhkl3d/ library (no public
API for now) which is used by the GUI to display and compute
diffractometer collisions (only the /K6C/ model). To build it you need
also [[https://projects.gnome.org/gtkglext/][gtkglext]] and
[[http://bulletphysics.org/wordpress/][bullet 2.82]]:

#+BEGIN_EXAMPLE
    $ ./configure --enable-hkl3d
    $ make
    $ sudo make install
#+END_EXAMPLE

if you want to work on the documentation you need the extra

-  [[http://www.gtk.org/gtk-doc/][gtk-doc]] for the api
-  [[http://sphinx.pocoo.org/][sphinx]] for the html and latex doc.
-  [[http://asymptote.sourceforge.net/][asymptote]] for the figures

#+BEGIN_EXAMPLE
    $ ./configure --enable-gtk-doc
    $ make
    $ make html
#+END_EXAMPLE

** Hacking hkl

*** Bug reporting

You can find the bug tracker here
[[https://bugs.debian.org/cgi-bin/pkgreport.cgi?repeatmerged=no&src=hkl][libhkl]]

-  Debian/Ubuntu:

   #+BEGIN_EXAMPLE
       $ reportbug hkl
   #+END_EXAMPLE

-  Other OS

   You just need to send an email:

   #+BEGIN_EXAMPLE
       To: submit@bugs.debian.org
       From: xxx@yyy.zzz
       Subject: My problem with hkl...

       Package: hkl
       Version: |version|

       I found this problem in hkl...
   #+END_EXAMPLE

*** Providing patchs

you can send your patch to [[picca@synchrotron-soleil.fr][Picca
Frédéric-Emmanuel]] using =git=

Here a minimalist exemple of the workflow to prepare and send a patch
for hkl. Suppose you wan to add a new feature to hkl create first a new
branch from the next one:

#+BEGIN_EXAMPLE
    $ git checkout -b my-next next
#+END_EXAMPLE

hack, hack:

#+BEGIN_EXAMPLE
    $ git commit -a
#+END_EXAMPLE

more hacks:

#+BEGIN_EXAMPLE
    $ git commit -a
#+END_EXAMPLE

now that your new feature is ready for a review, you can send by email
your work using git format-patch:

#+BEGIN_EXAMPLE
    $ git format-patch origin/next
#+END_EXAMPLE

and send generated files 0001\_xxx, 0002\_xxx, ... to the author.

** Howto add a diffractometer

To add a new diffractometer, you just need to copy the
hkl/hkl-engine-template.c into
hkl/hkl-engine-INSTITUT-BEAMLINE-INSTRUMENT.c where you replace the
upper case with the appropriate values.

The template file is compiled during the build process to ensure that it
is always valid.

Then you just need to follow the instruction found in the template. If
you need some precision about the process, do not hesitate to contact
the main author.

do not forgot also to add this new file into hkl/Makefile.am with other
diffractometers in the hkl\_c\_sources variable (please keep the
alphabetic order).
* Bindings

The hkl library use the gobject-introspection to provide automatic
binding for a few languages.

** Python

hkl computation:

has you can see there is 4 available solutions.

let's compute an hkl trajectory and select the first solution.

if we look at the 3 other solutions we can see that there is a problem
of continuity at the begining of the trajectory.

hey what's happend with theses solutions ! let's look closely to real
numbers. the last column is the distance to the diffractometer current
position. This distance is for now express like this:

$$\sum_{axes} \left|\text{current position} - \text{target position}\right|$$

#+BEGIN_EXAMPLE
    [0.0, 119.99999999999999, 0.0, -90.0, 0.0, 59.99999999999999] 0.0
    [0.0, -119.99999999999999, 0.0, -90.0, 0.0, -59.99999999999999] 6.28318530718
    [0.0, -60.00000000000005, 0.0, 90.0, 0.0, 59.99999999999999] 6.28318530718
    [0.0, 60.00000000000001, 0.0, 90.0, 0.0, -59.99999999999999] 6.28318530718

    [0.0, 117.7665607657826, 7.456826294401656, -92.39856410531434, 0.0, 60.33024982425957] 0.216753826612
    [0.0, -57.436310940366894, -7.456826294401656, 92.39856418853617, 0.0, 60.33024982425957] 6.41621345188
    [0.0, 62.2334392342174, -7.456826294401656, 92.39856410531434, 0.0, -60.33024982425957] 6.42197739723
    [0.0, -122.5636890596331, 7.456826294401656, -92.3985641885362, 0.0, -60.33024982425957] 6.50570308205

    [0.0, 115.89125602137928, 14.781064139466098, -94.7660423112577, 0.0, 61.314597086440706] 0.219062698235
    [0.0, -125.42334103772737, 14.781064139466098, -94.7660427050904, 0.0, -61.314597086440706] 6.53671995288
    [0.0, -54.57665896227262, -14.781064139466098, 94.76604270509038, 0.0, 61.314597086440706] 6.67989976726
    [0.0, 64.10874397862072, -14.781064139466098, 94.7660423112577, 0.0, -61.314597086440706] 6.71437170098

    [0.0, 114.39338605351007, 21.85448296702796, -97.074145033719, 0.0, 62.93506298693471] 0.218163667981
    [0.0, -128.54167683157993, 21.85448296702796, -97.07414574435087, 0.0, -62.93506298693471] 6.59846359365
    [0.0, -51.45832316842005, -21.85448296702796, 97.07414574435087, 0.0, 62.93506298693471] 6.93673746356
    [0.0, 65.60661394648993, -21.85448296702796, 97.074145033719, 0.0, -62.93506298693471] 7.03385205725

    [0.0, 113.28316795475283, 28.583837575232764, -99.29953499008337, 0.0, 65.16540747008955] 0.21459359225
    [0.0, -131.88223933078322, 28.583837575232764, -99.29953638594702, 0.0, -65.16540747008955] 6.69038531388
    [0.0, -48.11776066921677, -28.583837575232764, 99.29953638594702, 0.0, 65.16540747008955] 7.18296350386
    [0.0, 66.71683204524717, -28.583837575232764, 99.29953499008337, 0.0, -65.16540747008955] 7.37556986959

    [0.0, 112.56286877075006, 34.90573305321372, -101.42496979586187, 0.0, 67.97568017857415] 0.209053830457
    [0.0, -135.4128111996365, 34.90573305321372, -101.42497263302461, 0.0, -67.97568017857415] 6.81174779784
    [0.0, -44.58718880036348, -34.90573305321372, 101.4249726330246, 0.0, 67.97568017857415] 7.41581162393
    [0.0, 67.43713122924994, -34.90573305321372, 101.42496979586187, 0.0, -67.97568017857415] 7.7353201851

    [0.0, 112.2291126083182, 40.78594007247402, -103.43941832567457, 0.0, 71.33706722449408] 0.202280147961
    [0.0, -139.10795451001587, 40.78594007247402, -103.43942357602316, 0.0, -71.33706722449408] 6.96173845391
    [0.0, -40.89204548998411, -40.78594007247402, 103.43942357602312, 0.0, 71.33706722449408] 7.63358787543
    [0.0, 67.7708873916818, -40.78594007247402, 103.43941832567457, 0.0, -71.33706722449408] 8.10986069093

    [0.0, 112.27578927291766, 46.214916130901734, -105.33741042812996, 0.0, 75.22640762217479] 0.196576175748
    [0.0, -142.95061850160724, 46.214916130901734, -105.3374188005596, 0.0, -75.22640762217479] 7.13962155618
    [0.0, -37.04938149839278, -46.214916130901734, 105.33741880055959, 0.0, 75.22640762217479] 7.83557762281
    [0.0, 67.72421072708234, -46.214916130901734, 105.33741042812996, 0.0, -75.22640762217479] 8.49706672677

    [0.0, 112.697137434232, 51.201667684695856, -107.11797492933192, 0.0, 79.63023536264535] 0.202327153157
    [0.0, -146.9330984641471, 51.201667684695856, -107.11798610058318, 0.0, -79.63023536264535] 7.34491897177
    [0.0, -33.0669015358529, -51.201667684695856, 107.11798610058317, 0.0, 79.63023536264535] 8.02185610877
    [0.0, 67.30286256576798, -51.201667684695856, 107.11797492933192, 0.0, -79.63023536264535] 8.89597005568

    [0.0, 113.49085964586432, 55.76762791023837, -108.78347437395287, 0.0, 84.54867879242364] 0.208455586312
    [0.0, -151.05782007465257, 55.76762791023837, -108.78348605483542, 0.0, -84.54867879242364] 7.57761473366
    [0.0, -28.942179925347414, -55.76762791023837, 108.78348605483538, 0.0, 84.54867879242364] 8.19307323084
    [0.0, 66.50914035413568, -55.76762791023837, 108.78347437395287, 0.0, -84.54867879242364] 9.30675279514

    [0.0, 114.6614608037443, 59.941489465646214, -110.3385360479293, 0.0, 90.00000081324956] 0.215562935229
    [0.0, -155.33854118146962, 59.941489465646214, -110.33854432979601, 0.0, -89.99999918675044] 7.83839602383
    [0.0, -24.661458818530395, -59.941489465646214, 110.33854432979601, 0.0, 90.00000081324956] 8.3502621071
    [0.0, 65.3385391962557, -59.941489465646214, 110.3385360479293, 0.0, -89.99999918675044] 9.7307712883
#+END_EXAMPLE

as you can see for the first point of the trajectory, the 2nd, 3rd and
4th solutions have identical distances to the current position of the
diffractometer so they are un-ordered:

#+BEGIN_EXAMPLE
    [0.0, 119.99999999999999, 0.0, -90.0, 0.0, 59.99999999999999] 0.0
    [0.0, -119.99999999999999, 0.0, -90.0, 0.0, -59.99999999999999] 6.28318530718
    [0.0, -60.00000000000005, 0.0, 90.0, 0.0, 59.99999999999999] 6.28318530718
    [0.0, 60.00000000000001, 0.0, 90.0, 0.0, -59.99999999999999] 6.28318530718
#+END_EXAMPLE

then the problem arise with the second and third solution. you can see a
sort of reorganisation of the solution. 2 -> 3, 3 -> 4 and 4 -> 2 then
the order will stick unchanged until the end of the trajectory. this is
because the distance is computed relatively to the current position of
the diffractometer.:

#+BEGIN_EXAMPLE
    [0.0, 117.7665607657826, 7.456826294401656, -92.39856410531434, 0.0, 60.33024982425957] 0.216753826612
    [0.0, -57.436310940366894, -7.456826294401656, 92.39856418853617, 0.0, 60.33024982425957] 6.41621345188
    [0.0, 62.2334392342174, -7.456826294401656, 92.39856410531434, 0.0, -60.33024982425957] 6.42197739723
    [0.0, -122.5636890596331, 7.456826294401656, -92.3985641885362, 0.0, -60.33024982425957] 6.50570308205

    [0.0, 115.89125602137928, 14.781064139466098, -94.7660423112577, 0.0, 61.314597086440706] 0.219062698235
    [0.0, -125.42334103772737, 14.781064139466098, -94.7660427050904, 0.0, -61.314597086440706] 6.53671995288
    [0.0, -54.57665896227262, -14.781064139466098, 94.76604270509038, 0.0, 61.314597086440706] 6.67989976726
    [0.0, 64.10874397862072, -14.781064139466098, 94.7660423112577, 0.0, -61.314597086440706] 6.71437170098
#+END_EXAMPLE

#+BEGIN_QUOTE
  *warning*

  when you compute a trajectory, start from a valid position (the
  starting point must be the real first point of your trajectory) then
  use only the closest solution for the next points of the trajectory.
  (first solution of the geometries list)
#+END_QUOTE