.. _structure:

[Structure]: Crystal structure
========================================

Definition of the lattice structure and the atomic basis.

.. tabularcolumns:: |\Yc{0.15}|\Yc{0.17}|\Yc{0.13}|\Yl{0.55}|

+--------------------+------------------+-------------------+---------------------------------------------------------------+
| Parameter          |  Type            | Default           |  Description                                                  |
+====================+==================+===================+===============================================================+
| **name**           | `<string>`       |  "kkr_struct"     | Structure name (under which the SCMs will be stored to file)  |
+--------------------+------------------+-------------------+---------------------------------------------------------------+
| **path**           | `<string>`       |  NONE             | Directory where the SCMs are stored                           |
+--------------------+------------------+-------------------+---------------------------------------------------------------+
| **lmax**           | `<integer>`      |   2               | Basis function :math:`l`-cutoff                               |
+--------------------+------------------+-------------------+---------------------------------------------------------------+
| **lmax_high**      | `<integer>`      |   2               | :math:`l`-cutoff for higher partial waves                     |
+--------------------+------------------+-------------------+---------------------------------------------------------------+
| **lattice_scale**  | `<length>`       |  NONE             | Linear scale of the lattice vectors                           |
+--------------------+------------------+-------------------+---------------------------------------------------------------+
| **ws_radius**      | `<length>`       |  NONE             | Average Winger-Seitz radius, alternative to `lattice_scale`   |
+--------------------+------------------+-------------------+---------------------------------------------------------------+
| **lattice**        | `<matrix(3, 3)>` |  NONE             | Dimensionless translation vectors of the Bravais lattice;     |
|                    |                  |                   | the actual translation vectors are obtained by rescaling      |
|                    |                  |                   | using either `lattice_scale` or `ws_radius`                   |
+--------------------+------------------+-------------------+---------------------------------------------------------------+
| **sites_frac**     | `<site def>`     |  NONE             | Site definition with fractional coordinates                   |
+--------------------+------------------+-------------------+---------------------------------------------------------------+
| **sites_cart**     | `<site def>`     |  NONE             | Site definition with cartesian coordinates                    |
+--------------------+------------------+-------------------+---------------------------------------------------------------+
| **ewald_lambda**   | `<float>`        |   2.5             | Parameter :math:`\lambda` of Ewald's summation                |
+--------------------+------------------+-------------------+---------------------------------------------------------------+
| **ewald_rmax**     | `<float>`        |   4.5             | Size of the real-space cluster in Ewald's summation           |
+--------------------+------------------+-------------------+---------------------------------------------------------------+
| **ewald_kmax**     | `<float>`        |   4.5             | Size of the reciprocal-space cluster in Ewald's summation     |
+--------------------+------------------+-------------------+---------------------------------------------------------------+
| **lmax_mad**       | `<integer>`      | :math:`2 l_{max}` | :math:`l`-cutoff for the Madelung matrix                      |
+--------------------+------------------+-------------------+---------------------------------------------------------------+
| **cluster_nsites** | `<integer>`      |   75              | Minimum size of the cluster for real-space SCM                |
+--------------------+------------------+-------------------+---------------------------------------------------------------+
| **cluster_max**    | `<float>`        |   4.5             | Size of the cluster for real-space SCM                        |
+--------------------+------------------+-------------------+---------------------------------------------------------------+
| **cache_mode**     | `<string>`       | **full**          | Cache mode for Fourier-transformed SCM: **full**, **phases**, |
|                    |                  |                   | **none** (slow)                                               |
+--------------------+------------------+-------------------+---------------------------------------------------------------+
| **poscar**         | `<string>`       |   NONE            | VASP (>=5.x) format POSCAR file                               |
+--------------------+------------------+-------------------+---------------------------------------------------------------+

------

Site parameters are defined in one line starting with coordinates, followed by species and
by other parameters

----

+--------------------+-------------+------------------------------------+
|   `x`   `y`   `z`  |  Species    | <Other site parameters>            |
+--------------------+-------------+------------------------------------+

----

Species is provided either by an element symbol or by a reference to a corresponding
pseudo-species defined in section *[Alloy]*. The reference has the form `${spec-label}`
where `spec-label` is a user-defined label of the pseudo-species.

Other site parameters that can be listed after the species include

+--------------------+------------------+----------+---------------------------------------------------------------+
| Parameter          |  Type            | Default  |  Description                                                  |
+====================+==================+==========+===============================================================+
| **lcut**           | `<integer>`      | **lmax** | Local site :math:`l`-cutoff                                   |
+--------------------+------------------+----------+---------------------------------------------------------------+
| **psr**            | `<float>`        |   1.0    | Potential sphere radius in units of the average WS radius     |
+--------------------+------------------+----------+---------------------------------------------------------------+
| **mom**            | `<float>`        |   0.0    | Initial spin splitting or magnetic moment (`lsm_mode = fxm`)  |
+--------------------+------------------+----------+---------------------------------------------------------------+
| **lsm_mode**       | `<string>`       | **none** | Local spin moment mode: **none**, **fxm**, **dlm**, **lsf**   |
+--------------------+------------------+----------+---------------------------------------------------------------+
| **lsf_params**     | `<integer>`      |     3    | LSF effective dimension: 1, 2, or 3                           |
+--------------------+------------------+----------+---------------------------------------------------------------+


------

Notes:
******

    - the code will first try to read in SCM and Madelung matrix from files
      `<path>/<name>.scm` and `<path>/<name>.mcm`, respecively; if reading fails
      the constants will be calculated and stored to files under these names

    - if both `lattice_scale` and `ws_radius` are specified the latter will have priority

    - if `poscar` is specified other structure parameters are ignored