Merge branch 'rc'

doc/command-options.rst

@@ -71,8 +71,8 @@ Choice of force calculator
 ---------------------------
 
 Currently interfaces for VASP, Wien2k, Pwscf, Abinit, and Elk are
-prepared. Wien2k, Pwscf, Abinit and Elk interfaces are invoked with
-``--wienk2``, ``--pwscf``, ``--abinit``, and ``--elk`` options,
+prepared. Wien2k, Pwscf, Abinit, Elk and CRYSTAL interfaces are invoked with
+``--wienk2``, ``--pwscf``, ``--abinit``, ``--elk`` and ``--crystal`` options,
 respectively, and if none of these options or ``--vasp`` option is
 specified, VASP mode is invoked.
 
@@ -148,7 +148,7 @@ input file that contains the unit cell crystal structure, e.g.,
 ``--elk``
 ~~~~~~~~~~~~
 
-Pwscf mode is invoked with this option. Usually this option is used
+Elk mode is invoked with this option. Usually this option is used
 with ``--cell`` (``-c``) option or ``CELL_FILENAME`` tag to read Elk
 input file that contains the unit cell crystal structure, e.g.,
 
@@ -156,6 +156,19 @@ input file that contains the unit cell crystal structure, e.g.,
 
    % phonopy --elk -c elk-unitcell.in band.conf
 
+.. _crystal_mode:
+
+``--crystal``
+~~~~~~~~~~~~~
+
+CRYSTAL mode is invoked with this option. Usually this option is used
+with ``--cell`` (``-c``) option or ``CELL_FILENAME`` tag to read a CRYSTAL
+input file that contains the unit cell crystal structure, e.g.,
+
+::
+
+   % phonopy --crystal -c crystal.o band.conf
+
 .. _vasp_mode:
 
 ``--vasp``
@@ -190,6 +203,7 @@ directory. The default file names for the calculators are as follows::
    Abinit | unitcell.in
    Pwscf  | unitcell.in
    Elk    | elk.in
+   CRYSTAL| crystal.o
 
 Create ``FORCE_SETS``
 ----------------------
@@ -293,6 +307,15 @@ files.
 
    % phonopy --elk -f disp-001/INFO.OUT disp-002/INFO.OUT  ...
 
+CRYSTAL interface
+^^^^^^^^^^^^^^^^^
+
+``FORCE_SETS`` file is created from ``disp.yaml`` and CRYSTAL output
+files.
+
+::
+
+   % phonopy --crystal -f supercell-001.o supercell-002.o  ...
 
 .. _fz_force_sets_option:
 
@@ -407,7 +430,7 @@ printed out and phonopy stops without going to phonon analysis.
    % phonopy --symmetry
 
 This tag can be used together with the ``--cell`` (``-c``),
-``--abinit``, ``--pwscf``, ``--elk``, ``--wien2k``, or
+``--abinit``, ``--pwscf``, ``--elk``, ``--wien2k``, ``--crystal`` or
 ``--primitive_axis`` option.
 
 Input/Output file control

doc/crystal.rst

+.. _crystal_interface:
+
+CRYSTAL & phonopy calculation
+=========================================
+
+CRYSTAL program package has a robust built-in phonon calculation 
+workflow. However, the Phonopy interface enables convenient access
+to many phonon-related properties, such as subsequent Phono3py
+calculations of lattice thermal conductivity.
+
+Supported features
+---------------------------
+
+The CRYSTAL interface reads the unit cell from a CRYSTAL output file
+(lattice vectors, conventional atomic numbers, fractional atomic positions)
+For optimization outputs, the final geometry in the file is read.
+
+If dielectric tensor and effective Born charges are present, the interface
+creates a BORN file for Non-analytical correction (:ref:`nac_tag`).
+The recommended strategy is to carry out a Gamma-point frequency calculation 
+with INTENS and INTCPHF. This produces all required quantities and also confirms that
+the structure optimization has converged to a true local minimum.
+
+If ATOMSPIN keyword is present, magnetic moments are read from it. There
+is very little experience on using this feature, so be careful.
+
+How to run
+----------
+
+The workflow for a CRYSTAL-Phonopy calculation is outlined here using the
+Si example found in ``example/Si-CRYSTAL``. 
+
+In this example, the CRYSTAL output file is ``crystal.o``. 
+This is the default for the CRYSTAL interface, so, the ``-c crystal.o`` 
+parameter is not needed
+
+1) Create supercells with :ref:`crystal_mode` option::
+
+     % phonopy --crystal -d --dim="4 4 4"
+
+   In this example, 4x4x4 supercells are created. For every supercell file, the
+   interface creates a .d12 input file and an .ext structure file. The files 
+   ``supercell.d12/.ext`` contain the perfect supercell. The files
+   ``supercell-xxx.d12/.ext`` (``xxx`` are numbers) contain the supercells
+   with displacements. File ``disp.yaml`` is also generated, containing information 
+   about the supercell and the displacements.
+
+   In the case of the Si example, files ``supercell-001.d12`` and 
+   ``supercell-001.ext`` will be created.
+
+2) To make valid CRYSTAL input files, there are two possible options:
+
+   a) Manually: modify the generated supercell-xxx.d12 files by replacing 
+      the line ``Insert basis sets and parameters here`` with the 
+      basis set and computational parameters.
+
+   b) Recommended option: before generating the supercells, include a file named
+      ``TEMPLATE`` in the current directory. This file should contain the
+      basis sets and computational parameters for CRYSTAL (see the Si example).
+      When phonopy finds this file, it automatically generates complete
+      CRYSTAL input files in the step 1
+
+   Note that supercells with displacements must not be relaxed in the 
+   force calculations, because atomic forces induced by a small atomic 
+   displacement are what we need for phonon calculation. To get accurate
+   forces, TOLDEE parameter should be 10 or higher. Phonopy includes this
+   parameter and the necessary GRADCAL keyword automatically in the inputs.
+
+   Then, CRYSTAL supercell calculations are executed to obtain forces on
+   atoms, e.g., as follows::
+
+     % runcry14 supercell-001.d12
+
+3) To create ``FORCE_SETS``, that is used by phonopy, 
+   the following phonopy command is executed::
+
+     % phonopy --crystal -f supercell-001.o
+
+   Here ``.o`` files are the CRYSTAL output files from the force
+   calculations. saved text files of standard outputs of the
+   Pwscf calculations. All ``.o`` files corresponding to the generated
+   ``supercell-xxx.d12`` files have to be given in the above command. 
+   To run this command, ``disp.yaml`` has to be located in the current 
+   directory because the information on atomic displacements stored in 
+   ``disp.yaml`` are used to generate ``FORCE_SETS``. See some more detail at
+   :ref:`crystal_force_sets_option`.
+
+4) Now, Phonopy post-prcessing commands can be run. ``FORCE_SETS`` is
+   automatically read in. Create phonon dispersion plot with:
+
+   ::
+
+     % phonopy --crystal --dim="4 4 4" -p -s band.conf
+             _
+       _ __ | |__   ___  _ __   ___   _ __  _   _
+      | '_ \| '_ \ / _ \| '_ \ / _ \ | '_ \| | | |
+      | |_) | | | | (_) | | | | (_) || |_) | |_| |
+      | .__/|_| |_|\___/|_| |_|\___(_) .__/ \__, |
+      |_|                            |_|    |___/
+                                           1.11.6
+
+
+     Python version 2.7.3
+     Spglib version 1.9.9
+     Calculator interface: crystal
+     Band structure mode
+     Settings:
+       Supercell: [4 4 4]
+     Spacegroup: Fd-3m (227)
+     Computing force constants...
+     Reciprocal space paths in reduced coordinates:
+     [ 0.00  0.00  0.00] --> [ 0.50  0.00  0.50]
+     [ 0.50  0.00  0.50] --> [ 0.50  0.25  0.75]
+     [ 0.50  0.25  0.75] --> [ 0.37  0.38  0.75]
+     [ 0.38  0.38  0.75] --> [ 0.00  0.00  0.00]
+     [ 0.00  0.00  0.00] --> [ 0.50  0.50  0.50]
+     [ 0.50  0.50  0.50] --> [ 0.63  0.25  0.63]
+     [ 0.62  0.25  0.62] --> [ 0.50  0.25  0.75]
+     [ 0.50  0.25  0.75] --> [ 0.50  0.50  0.50]
+     [ 0.50  0.50  0.50] --> [ 0.37  0.37  0.75]
+     [ 0.62  0.25  0.62] --> [ 0.50 -0.00  0.50]
+                      _
+        ___ _ __   __| |
+       / _ \ '_ \ / _` |
+      |  __/ | | | (_| |
+       \___|_| |_|\__,_|
+
+
+   |crystal-band|
+
+   .. |crystal-band| image:: Si-crystal-band.png
+			   :width: 33%
+
+   For further settings and command options, see the general Phonopy documentation
+   :ref:`setting_tags` and :ref:`command_options`, respectively, and
+   for examples, see :ref:`examples_link`.
+
+Non-analytical term correction (Optional)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The workflow for a CRYSTAL-Phonopy calculation with Non-analytical correction
+is outlined here using the NaCl example found in ``example/NaCl-CRYSTAL``.
+
+In this example, the CRYSTAL output file is ``crystal.o``.
+This is the default for the CRYSTAL interface, so, the ``-c crystal.o``
+parameter is not needed.
+
+To activate non-analytical term correction, :ref:`born_file` is
+required. This file contains the Born effective charges
+and the dielectric tensor. They can be calculated with CRYSTAL.
+The recommended strategy is to carry out a Gamma-point frequency calculation
+with INTENS and INTCPHF. This produces all required quantities and also confirms that
+the structure optimization has converged to a true local minimum.
+(see the FREQCALC-INTENS-INTCPHF block in the beginning of ``crystal.o``)
+
+The workflow is very similar to the Si example below:
+
+1) Create displaced supercells::
+
+     phonopy --crystal --dim="4 4 4" -d
+
+   Note that now the CRYSTAL interface automatically creates the ``BORN``
+   file. It should look like this::
+
+     default
+     1.8126 0.0000 0.0000 0.0000 1.8126 0.0000 0.0000 0.0000 1.8126
+     1.0238 -0.0000 -0.0000 -0.0000 1.0238 0.0000 -0.0000 0.0000 1.0238
+     -1.0238 0.0000 0.0000 0.0000 -1.0238 0.0000 0.0000 0.0000 -1.0238
+
+   However, if you don't want to run a FREQCALC-INTENS-INTCPHF calculation,
+   but have the necessary data from some other source, you can create
+   the ``BORN`` file manually following the ``BORN`` format
+   (:ref:`born_file`).
+
+2) Run the supercell inputs with CRYSTAL
+
+3) Collect forces::
+
+     phonopy --crystal -f supercell-*o
+
+4) Calculate phonon dispersion data into band.yaml and save band.pdf,
+   using Non-analytical correction --nac::
+
+     phonopy --crystal --dim="4 4 4" -p -s --nac band.conf
+
+   |crystal-band-nac|
+
+   .. |crystal-band-nac| image:: NaCl-crystal-band-NAC.png
+                               :width: 33%
+

doc/gruneisen.rst

@@ -63,10 +63,10 @@ showing the values on the plot. Instead the values at the neighboring
 
 .. _gruneisen_calculators:
 
-Abinit, Pwscf, and Wien2k interfaces
--------------------------------------
+Abinit, Pwscf, Wien2k, and CRYSTAL interfaces
+---------------------------------------------
 
-``--abinit``, ``--pwscf``, or ``--wien2k`` options can be specified
+``--abinit``, ``--pwscf``, ``--wien2k``, or ``--crystal`` options can be specified
 for corresponding calculators and the crystal structure file format
 should be different from that of the VASP format. An Abinit example is
 as follows::
@@ -79,7 +79,7 @@ as follows::
 Command options
 ----------------
 
-If one of ``--abinit``, ``--pwscf``, or ``--wien2k`` options is
+If one of ``--abinit``, ``--pwscf``, ``--wien2k``, or ``--crystal`` options is
 specified, the interface mode is changed to it. The unit conversion
 factor to THz is appropriately selected and its crystal structure file
 format is accepted. If none of them is specified, as the VASP

doc/index.rst

@@ -52,7 +52,8 @@ Selected features
   :ref:`Siesta <siesta_interface>`,
   :ref:`Elk <elk_interface>`,
   :ref:`FHI-aims <FHI_aims_interface>`,
-  :ref:`Wien2k <wien2k_interface>`
+  :ref:`Wien2k <wien2k_interface>`,
+  :ref:`CRYSTAL <crystal_interface>`
 - :ref:`Python APIs <phonopy_module>`
   
 |i0| |i1| |i2| |i3|

doc/interfaces.rst

@@ -3,7 +3,7 @@
 Interfaces to calculators
 ==========================
 
-The interfaces for VASP, Wien2k, Pwscf, Abinit, and Elk are built in
+The interfaces for VASP, Wien2k, Pwscf, Abinit, Elk and CRYSTAL are built in
 to the usual phonopy command. See the command options and how to
 invoke each of them at :ref:`force_calculators`. 
 
@@ -20,8 +20,9 @@ Physical unit systems used for the calculators are as follows::
    Abinit  | au (bohr)  AMU           eV/Angstrom   eV/Angstrom.au
    Siesta  | au (bohr)  AMU           eV/Angstrom   eV/Angstrom.au
    elk     | au (bohr)  AMU           hartree/au    hartree/au^2
+   CRYSTAL | Angstrom   AMU           eV/Angstrom   eV/Angstrom^2
 
-For these sets of physical properties, phonon frequency is calcualted
+For these sets of physical properties, phonon frequency is calculated
 in THz.
 
 Default file name, value, and conversion factor
@@ -39,6 +40,7 @@ used as shown below::
    Abinit  | unitcell.in
    Siesta  | input.fdf
    Elk     | elk.in
+   CRYSTAL | crystal.o
 
 Default displacement distances
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -55,6 +57,7 @@ shown below::
    Abinit  | 0.02 au (bohr)
    Siesta  | 0.02 au (bohr)
    Elk     | 0.02 au (bohr)
+   CRYSTAL | 0.01 Angstrom
 
 .. _nac_default_value_interfaces:
 
@@ -69,6 +72,7 @@ Default unit conversion factor for non-analytical term correction
    Abinit  | 51.422090
    Siesta  | 51.422090
    Elk     | 1
+   CRYSTAL | 14.399652
 
 
 Interface to force calculator
@@ -85,6 +89,7 @@ Short tutorials for force calculators are found in the following pages.
    abinit
    siesta
    elk
+   crystal
 
 Interface to  VASP DFPT force constants
 ---------------------------------------

doc/phonopy-module.rst

@@ -79,8 +79,9 @@ is 0.01.)
 The frequency unit conversion factor to THz has to be set by using the ``factor``
 keyword in ``Phonopy`` class. The factors are ``VaspToTHz`` for VASP,
 ``Wien2kToTHz`` for Wien2k, ``AbinitToTHz`` for Abinit,
-``PwscfToTHz`` for Pwscf, ``ElkToTHz`` for Elk, and ``SiestaToTHz``
-for Siesta. ``VaspToTHz`` is the default value. For example::
+``PwscfToTHz`` for Pwscf, ``ElkToTHz`` for Elk, ``SiestaToTHz``
+for Siesta, and ``CrystalToTHz for CRYSTAL``. ``VaspToTHz`` is the default value. 
+For example::
 
    from phonopy.units import AbinitToTHz
 

doc/setting-tags.rst

@@ -199,8 +199,8 @@ mean square displacements.
 
 The default values for calculators are those to convert frequency
 units to THz. The default conversion factors for ``wien2k``,
-``abinit``, ``pwscf``, and ``elk`` are 3.44595, 21.49068, 108.9708,
-and 154.1079 respectively. These are determined following the physical
+``abinit``, ``pwscf``, ``elk``, and CRYSTAL are 3.44595, 21.49068, 108.9708,
+154.1079, and 15.633302 respectively. These are determined following the physical
 unit systems of the calculators. How to calcualte these conversion
 factors is explained at :ref:`physical_unit_conversion`.
 

example/NaCl-CRYSTAL/README

+NaCl phonon dispersions with non-analytical correction
+
+CRYSTAL output file is crystal.o. This is the default file name
+for the CRYSTAL interface, so, the -c crystal.o parameter is not needed
+
+CRYSTAL output file crystal.o includes the Born effective
+charges and the dielectric tensor 
+(from FREQCALC-INTENS-INTCPHF, see the input in the beginning of crystal.o)
+
+1) Create displaced supercells:
+   phonopy --crystal --dim="4 4 4" -d
+   Complete CRYSTAL inputs can be prepared manually
+   or with the help of a template (see TEMPLATE)
+
+2) Run the supercell inputs with CRYSTAL
+   Here supercell-001.o and supercell-002.o have been pre-calculated.
+
+3) Collect forces:
+   phonopy --crystal -f supercell-*o
+
+4) Calculate phonon dispersion data into band.yaml and save band.pdf:
+   phonopy --crystal --dim="4 4 4" -p -s band.conf
+
+   Take the non-analytical correction into account (see BORN file)
+   phonopy --crystal --dim="4 4 4" -p -s --nac band.conf 
+   
+   Plot the phonon dispersion in cm^{-1} units:
+   (factor = CrystalToTHz * THzToCm = 15.633302 * 33.356410)
+   phonopy --crystal --dim="4 4 4" -p -s --nac --factor=521.47083 band.conf
+
+   Create a formatted plot (here band.yaml is in cm^{-1) units):
+   bandplot --fmin=0 --line --ylabel="Frequency (cm\$^{-1}\$)" "--band_labels=`grep BAND_LABELS band.conf | cut -d= -f2-`" -o dispersion.pdf

example/NaCl-CRYSTAL/TEMPLATE

+11 5
+0 0 5 2.0 1.0
+  4098.2003908     -.58535911879E-02
+  616.49374031     -.43647161872E-01
+  139.96644001     -.19431465884
+  39.073441051     -.48685065731
+  11.929847205     -.41881705137
+0 0 3 2.0 1.0
+  20.659966030      .85949689854E-01
+  1.9838860978     -.56359144041
+  .64836323942     -.51954009048
+0 0 1 1.0 1.0
+  0.32              1.0000000000
+0 1 1 0.0 1.0
+  0.16              1.0 1.0
+0 2 5 6.0 1.0
+  75.401862017     .154353625324E-01
+  17.274818978     .997382931840E-01
+  5.1842347425     .312095939659
+  1.6601211973     .492956748074
+  .51232528958     .324203983180
+17 7
+0 0 5 2.0 1.0
+  10449.827566      0.19708362484E-02
+  1571.7365221      0.14754727977E-01
+  357.12065523      0.66679112875E-01
+  100.25185935      0.17228924084
+  30.812727554      0.15883786100
+0 0 3 2.0 1.0
+  51.923789434     -0.10009298909
+  5.7045760975      0.60841752753
+  2.3508376809      0.54352153355
+0 0 1 2.0 1.0
+ 0.49731621872       1.0000000000
+0 1 1 0.0 1.0
+ 0.21000000000      1.0 1.0
+0 2 5 6.0 1.0
+  307.66790569     -0.87801484118E-02
+  72.102015515     -0.63563355471E-01
+  22.532680262     -0.24016428276
+  7.8991765444     -0.47798866557
+  2.8767268321     -0.38515850005
+0 2 1 5.0 1.0
+  0.77358997479      1.0000000000
+0 3 1 0.0 1.0
+ 0.65000000000       1.0000000000
+99 0
+END
+DFT
+PBE0
+END
+SHRINK
+1 1
+TOLINTEG
+8 8 8 8 16
+MAXCYCLE
+60
+FMIXING
+80
+BROYDEN
+0.01 50 4
+NOSHIFT
+EXCHSIZE
+30000000
+BIPOSIZE
+30000000

example/NaCl-CRYSTAL/band.conf

+BAND = 0 0 0    1/2 0 1/2    1/2 1/4 3/4    3/8 3/8 3/4    0 0 0    1/2 1/2 1/2    5/8 1/4 5/8    1/2 1/4 3/4    1/2 1/2 1/2    3/8 3/8 3/4,    5/8 1/4 5/8    1/2 0 1/2
+BAND_LABELS = $\Gamma$ X W K $\Gamma$ L U W L K:U X
+BAND_POINTS = 101

example/Si-CRYSTAL/README

+Si phonon dispersions
+
+CRYSTAL output file is crystal.o. This is the default file name
+for the CRYSTAL interface, so, the -c crystal.o parameter is not needed
+
+1) Create displaced supercells:
+   phonopy --crystal --dim="4 4 4" -d
+   Complete CRYSTAL inputs can be prepared manually
+   or with the help of a template (see TEMPLATE)
+
+2) Run the supercell input with CRYSTAL
+   Here supercell-001.o has been pre-calculated.
+
+3) Collect forces:
+   phonopy --crystal -f supercell-*o
+
+4) Calculate phonon dispersion data into band.yaml and save band.pdf:
+   phonopy --crystal --dim="4 4 4" -p -s band.conf
+
+   Plot the phonon dispersion in cm^{-1} units:
+   (factor = CrystalToTHz * THzToCm = 15.633302 * 33.356410)
+   phonopy --crystal --dim="4 4 4" -p -s --factor=521.47083 band.conf
+
+   Create a formatted plot (here band.yaml is in cm^{-1) units):
+   bandplot --fmin=0 --line --ylabel="Frequency (cm\$^{-1}\$)" "--band_labels=`grep BAND_LABELS band.conf | cut -d= -f2-`" -o dispersion.pdf
+

example/Si-CRYSTAL/TEMPLATE

+14 7
+0 0 5 2.0 1.0
+  6903.7118686      0.13373962995E-02
+  1038.4346419      0.99966546241E-02
+  235.87581480      0.44910165101E-01
+  66.069385169      0.11463638540
+  20.247945761      0.10280063858
+0 0 3 2.0 1.0
+  34.353481730      0.70837285010E-01
+  3.6370788192     -0.43028836252
+  1.4002048599     -0.41382774969
+0 0 1 2.0 1.0
+ 0.25943211957       1.0000000000
+0 1 1 0.0 1.0
+ 0.12000000000       1.0 1.0
+0 2 5 6.0 1.0
+  179.83907373      0.61916656462E-02
+  41.907258846      0.43399431982E-01
+  12.955294367      0.15632019351
+  4.4383267393      0.29419996982
+  1.5462247904      0.23536823814
+0 2 1 2.0 1.0
+ 0.40981363585       1.0000000000
+0 3 1 0.0 1.0
+ 0.35000000000       1.0000000000
+99 0
+ENDBAS
+DFT
+PBE0
+END
+SHRINK
+1 1
+TOLINTEG
+8 8 8 8 16
+MAXCYCLE
+60
+FMIXING
+80
+BROYDEN
+0.01 50 4
+NOSHIFT
+EXCHSIZE
+30000000
+BIPOSIZE
+30000000

example/Si-CRYSTAL/band.conf

+BAND = 0 0 0    1/2 0 1/2    1/2 1/4 3/4    3/8 3/8 3/4    0 0 0    1/2 1/2 1/2    5/8 1/4 5/8    1/2 1/4 3/4    1/2 1/2 1/2    3/8 3/8 3/4,    5/8 1/4 5/8    1/2 0 1/2
+BAND_LABELS = $\Gamma$ X W K $\Gamma$ L U W L K:U X
+BAND_POINTS = 101