.. raw:: html
.. role:: red
.. _label_tutorial_si_python:
Silicon with Python
-------------------
.. admonition:: At a glance
:class: tip
:Goal: Run the phonon and thermal-conductivity calculations of the :ref:`Si tutorial `
from a Python script, and analyze the results with NumPy and Matplotlib.
:You will learn:
- how to run **anphon** from Python dictionaries with ``anphon.run``
- how to read the output files through the returned ``Result``
- how to get frequencies and eigenvectors at arbitrary :math:`q` points with ``anphon.Phonon``
- how to read ``PREFIX.kappa.h5`` into a dictionary with ``Result.h5``
:Prerequisites: :ref:`The Si tutorial ` and the ``alamode-python`` Python package
(see :ref:`anphon_python_install`), plus Matplotlib.
:Example files: ``example/Si/python``
:Run time: The whole script takes a few seconds.
The Python package ``anphon`` runs the same calculations as the command-line program,
inside the Python process (see :ref:`anphon_python` for the full reference).
In this tutorial, we redo the phonon dispersion, phonon DOS, and thermal conductivity of Si from
the :ref:`Si tutorial ` with the force constants in **example/Si/reference**.
The complete script is :red:`si_python.py`:
:download:`Download si_python.py <../../../example/Si/python/si_python.py>`
It finds the force constants relative to its own location, so it can be run from any directory.
The outputs are written to the subdirectories :red:`bands`, :red:`dos`, and :red:`kappa` of the current directory::
$ mkdir si_python && cd si_python
$ python /path/to/alamode/example/Si/python/si_python.py
anphon prints its usual log for each run.
#. :ref:`Phonon dispersion and DOS `
#. :ref:`Frequencies and eigenvectors at arbitrary q `
#. :ref:`Thermal conductivity `
.. _tutorial_SiPy_step1:
1. Phonon dispersion and DOS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After the imports, the script locates **example/Si/reference**:
.. literalinclude:: ../../../example/Si/python/si_python.py
:language: python
:start-at: REF =
:end-before: # --- Step 1
``anphon.run`` takes one dictionary per input field (``general``, ``cell``, ``kpoint``, ...).
It writes the input file :red:`si222.in` in ``workdir`` and runs it, exactly as ``anphon si222.in`` would.
The two runs below are the band structure (``KPMODE = 1``) and the DOS on a :math:`20\times 20\times 20` mesh (``KPMODE = 2``)
of :ref:`step 4 of the Si tutorial ` (``DELTA_E = 2`` gives a finer energy grid for the DOS than the default 10 cm\ :sup:`-1`):
.. literalinclude:: ../../../example/Si/python/si_python.py
:language: python
:start-at: # --- Step 1
:end-before: # .bands: column 0
Because anphon runs inside ``workdir``, a relative :anphon:`FCSFILE` would be looked up there;
the script therefore passes an absolute path.
``anphon.format_input(general=..., kpoint=...)`` returns the input text without running anything,
which is handy to check what will be written.
The returned ``Result`` knows the output directory and :anphon:`PREFIX`:
``bands.files()`` lists the files ``si222.*`` (here ``['si222.bands', 'si222.in']``; the input file written by ``run`` is included)
and ``bands.path(".bands")`` gives the path of :red:`si222.bands`.
The text outputs are read with ``numpy.loadtxt`` and plotted with Matplotlib:
.. literalinclude:: ../../../example/Si/python/si_python.py
:language: python
:start-at: # .bands: column 0
:end-before: # --- Step 2
.. figure:: ../../img/Si_python.png
:scale: 70%
:align: center
Phonon dispersion and DOS of Si plotted by si_python.py.
.. _tutorial_SiPy_step2:
2. Frequencies and eigenvectors at arbitrary q
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``anphon.Phonon`` returns harmonic frequencies and eigenvectors as NumPy arrays for any list of :math:`q` points:
.. literalinclude:: ../../../example/Si/python/si_python.py
:language: python
:start-at: # --- Step 2
:end-before: # --- Step 3
The :math:`q` points are given in fractional coordinates of the reciprocal primitive lattice.
The frequencies come in cm\ :sup:`-1` with shape ``(nq, nmodes)``, where ``nmodes`` is three times the number of atoms
in the primitive cell (6 for Si), and the eigenvectors with shape ``(nq, nmodes, nmodes)``,
laid out as ``evec[iq, imode, 3 * iatom + ixyz]``. The script prints:
.. code-block:: none
(3, 6) (3, 6, 6)
[[ 0. 0. 0. 512.9 512.9 512.9]
[136.7 136.7 408.8 408.8 461.3 461.3]
[105.2 105.2 372.5 413. 489.4 489.4]]
[[ 0.631+0.j 0.32 +0.j 0. +0.j]
[-0.631+0.j -0.32 +0.j 0. +0.j]]
The rows are :math:`\Gamma`, X, and L, and agree with the dispersion above.
The last array is the highest mode at :math:`\Gamma`: the two Si atoms move in opposite directions (optical mode).
Since this mode is threefold degenerate, the direction of the displacement within the degenerate subspace is arbitrary.
The force-constant file (HDF5 or XML) carries the species, so ``kd`` is optional
(the masses then come from the element table unless :anphon:`MASS` is given in ``general``).
The HDF5 file written by **alm** also carries the primitive cell defined by :alm:`PRIMCELL` in the **alm** input,
so ``cell`` can be omitted as well (pass ``cell=dict(a=..., lattice=...)`` for a file fitted without :alm:`PRIMCELL`).
An XML force-constant file does not contain the primitive cell, so ``cell`` is always needed for it.
``Phonon`` is quiet by default; pass ``general=dict(VERBOSITY=1)`` to see the anphon log.
Ask for all :math:`q` points in one call, because each call runs anphon once.
.. _tutorial_SiPy_step3:
3. Thermal conductivity
~~~~~~~~~~~~~~~~~~~~~~~
The thermal conductivity in the RTA (:ref:`step 6 of the Si tutorial `) needs the cubic force constants.
The script reads :red:`si222_cubic.h5` and runs ``MODE = kappa`` in :red:`kappa/`
on an :math:`8\times 8\times 8` mesh, which takes about a second:
.. literalinclude:: ../../../example/Si/python/si_python.py
:language: python
:start-at: # --- Step 3
``res.h5("kappa")`` reads :red:`si222.kappa.h5` into nested dictionaries of NumPy arrays.
The keys are the raw layout of the file described in :ref:`label_hdf5_kappa`;
this reader is provisional and may change in a 2.x release (see :ref:`anphon_python_stability`).
The script prints
.. code-block:: none
100 K 434.7 W/mK
200 K 148.2 W/mK
300 K 90.5 W/mK
...
1000 K 26.3 W/mK
The value at 300 K is lower than the result on the :math:`10\times 10\times 10` mesh of the Si tutorial (about 104 W/mK).
Change ``mesh`` to check the convergence.
The script removes an old :red:`si222.kappa.h5` before the run, because anphon would otherwise restart from it
and stop when the mesh differs.
For larger meshes, run the script under MPI as the command-line program::
$ mpirun -np 4 python si_kappa.py
Every ``anphon.run`` call is then collective: all ranks must call it with the same arguments.
``anphon.Phonon`` is serial only, so put the ``kappa`` run into a script of its own (here ``si_kappa.py``) before using more than one process.
See :ref:`anphon_python_mpi` for details.