Usage
=========

Main classes
------------

Main classes and corresponding objects are tabulated below:

+-------------------------+----------------------------+
| Classes                 |  Objects                   |
+=========================+============================+
| ``LatticeParameters``   | Lattice Parameters         |
+-------------------------+----------------------------+
| ``Atom``                | Atom                       |
+-------------------------+----------------------------+
| ``AtomInCell``          | Atom with its fractiontal  |
|                         | coordinates in a unit cell |
+-------------------------+----------------------------+
| ``UnitCell``            | Unit cell                  |
+-------------------------+----------------------------+
| ``PolyXtal``            | Ideal Polycrystalline      |
|                         | specimen                   |
+-------------------------+----------------------------+
| ``SingleXtal``          | Single-crystal specimen    |
+-------------------------+----------------------------+
| ``NonidealPolyXtal``    | Nonideal Polycrystalline   |
|                         | specimen                   |
+-------------------------+----------------------------+
| ``Xray``                | X-ray spectrum             |
+-------------------------+----------------------------+
| ``HKL``                 | Miller index triplet       |
+-------------------------+----------------------------+
| ``Curve1D``             | 1D diffraction curve       |
+-------------------------+----------------------------+
| ``Pattern2D``           | 2D diffraction pattern     |
+-------------------------+----------------------------+
| ``Detector``            | Planar detector            |
+-------------------------+----------------------------+
| ``CylindricalDetector`` | Cylindrical detector       |
+-------------------------+----------------------------+

Examples
--------


Bragg diffraction of an ideal polycrystalline specimen
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python
    :linenos:

    from datad import unitcell_Ta, Detector, PolyXtal, Curve1D, Xray
    
    if __name__ == "__main__":
        Ta = PolyXtal(unitcell_Ta)
        xray = Xray.from_wavelength(1.54)
        c1d = Curve1D(Ta, xray)
        c1d.calc_peaks(
            max_tth=115,
            is_degree=True)
        detector = Detector(
            normal=(0, 0, 1), vx=(1, 0, 0),
            sizex=50, sizey=25,
            dist=10,
            ponix=25, poniy=25 / 2)
        detector.project_peaks(
            c1d,
            inc=(0,0,-1), vx=(1,0,0))
        detector.calc_to_pic(
            tth_res=0.08, ps=0.01, is_degree=True)
        detector.save_pic("ta.tif")

Cylindrical detector
""""""""""""""""""""

Class ``CylindricalDetector`` is a subclass of ``Detector`` and its methods is identical to
that of ``Detector`` except for instantiation. For example, one can instantiate a ``CylindricalDetector``
as follows:

.. code-block:: python
    :linenos:
    
    from datad import CylindricalDetector
    
    detector = CylindricalDetector(
        normal=(0, 0, 1), vx=(1, 0, 0),
        sizex=90, sizey=10,
        dist=10,
        ponix=10, poniy=5,
        radius=30,
        start_angle=5, is_degree=True)


Laue diffraction of a single-crystal specimen
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python
    :linenos:

    from datad import UnitCell, Pattern2D, SingleXtal, Xray
    from numpy import linspace

    if __name__ == "__main__":
        unitcell_KCl = UnitCell.from_array(
            (3.634, 3.634, 3.634, 90, 90, 90),
            (("K", (0, 0, 0)), ("Cl", (0.5, 0.5, 0.5)),),
            is_degree=True)
        KCl = SingleXtal.from_rcp_vectors(
            unitcell_KCl,
            x=(1, 0, 0),
            z=(0, 0, 1))
        KCl.strain(0.1, 0, 0, 0, 0, 0)
        KCl.rotate_by_axis_angle(
            axis=(1, 1, 1),
            angle=30,
            is_degree=True)
        xray = Xray.from_energy(linspace(1, 100, 500))
        p2d = Pattern2D(
            KCl, xray,
            inc=(0, 0, -1), vx=(1, 0, 0))
        p2d.calc_peaks(sort_by="intensity")

        # initialize a detector

        detector.project_peaks(p2d)
        detector.calc_to_pic(
            ps=0.01,
            sigmax=10, sigmay=10)

Laue diffraction of a nonideal polycrystalline specimen
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``NonidealPolyXtal`` is identical to ``SingleXtal`` except their instantiation methods.

One can instantiate a texture-free nonideal polycrystalline specimen with 10000 grains as follows:

.. code-block:: python
    :linenos:

    npx = NonidealPolyXtal.uniform(unitcell, 10000)

If a user-defined texture is desired, a space-separated text file containing the discrete
orientation distribution function (ODF) is needed, along with the static method ``NonidealPolyXtal.from_odf()``:

.. code-block:: python
    :linenos:

    npx = NonidealPolyXtal.from_odf(
        unitcell,
        "odf.txt", is_degree=True,
        phi1_col=3, Phi_col=4, phi2_col=5, intensity_col=6,
        num_grains=50000,
        phi1_prec=5, Phi_prec=5, phi2_prec=5)