.. _crystal-structure:

Entering Crystal Structures 
===============================

For many different tasks performed in the PM suite, a crystal structure, or
some component of a crystal structure, must be provided to the code. Most
likely, this will be done using a yaml input file, and the two required key words
are **vec** and **atoms**, which will contain the lattice vectors and the basis atoms, respectively.
Considering the flourite structure, the most straightforward yaml file would be:

.. code-block:: yaml
  :caption: structure.yml

  vec: 
    [[0.000000,2.764309,2.764309],
     [2.764309,0.000000,2.764309],
     [2.764309,2.764309,0.000000]]
  atoms:
    - Ca: 
       [[0,0,0]]
    - F:
       [[0.25,0.25,0.25],
        [0.75,0.75,0.75]]

The code will infer that there is one basis atom labeled *Ca* and two basis atoms labeled *F*.

When entering matrices, we will always run the input through our general array
parser (see parse_array if interested in the details). Therefore, there are many different
options for entering a matrix as a string. For example, consider:

.. code-block:: yaml
  :caption: structure.yml

  scale: 2.764309
  vec: |
     0 1 1
     1 0 1
     1 1 0
  atoms:
    - Ca: |
       0 0 0
    - F: |
       1/4 1/4 1/4
       3/4 3/4 3/4

where **scale** is a constant that multiplies all lattice vectors (a list of
three constants could have been provided), and the vertical lines tells yaml to
expect a text block.  Our parser has a hierarchy of delimiters, ranging from
space, comma, semicolon, newline. In the above example, we have two types of
delimiters (i.e. spaces and newlines), which tells the code to form a matrix. 
One of the more compact ways to achieve the same input files as above is:

.. code-block:: yaml
  :caption: structure.yml

  scale: 2.764309
  vec: 0 1 1 ; 1 0 1 ; 1 1 0
  atoms:
    - Ca: 0 0 0
    - F: 1/4 1/4 1/4 ; 3/4 3/4 3/4

.. Note::
  
  In the case of syntax error in YAML file, a ``RuntimeError`` will be thrown indicating the an error has
  occurred during the YAML loading process. For example, with the following text as YAML input:

  .. code-block:: yaml

    scale: 2.764309
    vec: |
       0 1 1 ; 1 0 1 ; 1 1 0
    atoms:
      - Ca: |
        0 0 0
      - F: |
        1/4 1/4 1/4 ; 3/4 3/4 3/4

  The following error message will appear:

  .. code-block::

      RuntimeError: Following error occured processing input YAML string:
      ScannerError: while scanning a simple key
        in "<unicode string>", line 6, column 5
      could not find expected ':'
        in "<unicode string>", line 7, column 3