This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Command Line Functionality

Executing core functionality of PM from the command line.

1: Input tags
2: Array Parser
3: Prototype Crystals
4: Symmetrizing atoms in crytal
5: Symmetrizing displacements in Crystal
6: Products of Irreducible Representations
7: pm-convert-id-main-to-dev
8: pm-phonons-via-irr-derivatives

Most key tasks can be performed from the command line, and here we document all such functionality.

1 - Input tags

Input tags used by PM from the command line.

List of Input Tags

lattice_vectors, basis_atoms,

lattice_vectors

Testing 1 2 3


type:	real, matrix
dimension:	3x3
scripts:	xx, yy

type: matrix

dimension: 3x3

basis_atoms

Name	Description
lattice_vectors	Lattice vectors in three dimensions, specified by a row-stacked 3x3 matrix.
basis_atoms	Basis atoms of crystal structure.
supa	A matrix of integers which left multiplies lattice_vectors to create a superlattice.
axial_strain	A vector of three floats which specifies the axial strain.
strain	A 3x3 real, symmetric matrix which specifies a general state of strain.
point_group	A string specifying the point group in Schoenfiles notation.
kpoint	A three dimensional vector specifying a kpoint.
qpoint	A three dimensional vector specifying a qpoint.
kpoint_mesh	A vector of three integers, specifying the kpoint mesh for electrons.
qpoint_mesh	A vector of three integers, specifying the qpoint mesh for phonons.
kpoint_path	A row stacked matrix of kpoints used to create a path through the BZ for plotting electronic bands.
qpoint_path	A row stacked matrix of qpoints used to create a path through the BZ for plotting phononic bands.
force_constants	A dictionary with keys being three dimensional vectors and values being NxN matrices, where N is the number of degrees of freedom in the unit cell.

Tags with vector or matrix values

Many variables will be vectors or matrices, and all such variables will be processed by our text parser. Below are several examples which illustrate the variety of different ways that vectors may be input.

lattice_vectors: 
  [[0,0.5,0.5],
   [0.5,0,0.5],
   [0.5,0.5,0]]

lattice_vectors: |
   0 1/2 1/2
   1/2 0 1/2
   1/2 1/2 0
  
lattice_vectors: 0 1/2 1/2; 1/2 0 1/2; 1/2 1/2 0

2 - Array Parser

Entering vectors or matrices at command line or in a YAML file.

For many different tasks performed in the PM suite, a vector or matrix must be provided at the command line or in a yaml file. PM has an array parser which allows substantial flexibility to facilitate this (see parse_array if interested in the details).

Consider entering the lattice vectors tag. All of the below are valid syntax. The parser excepts delimiters: line break, semi-colon, comma, space, where line break takes highest position. If only one delimiter is present, the result will be a vector, while two delimiters yields a matrix, etc.

lattice_vectors: 
  [[0.000000,2.764309,2.764309],
   [2.764309,0.000000,2.764309],
   [2.764309,2.764309,0.000000]]

lattice_vectors: |
   0   1/2 1/2
   1/2 0   1/2
   1/2 1/2 0

lattice_vectors: 0 1/2 1/2 ; 1/2 0 1/2 ; 1/2 1/2 0
lattice_vectors: 0 1/2 1/2 , 1/2 0 1/2 , 1/2 1/2 0
lattice_vectors: 0,1/2,1/2 ; 1/2,0,1/2 ; 1/2,1/2,0
lattice_vectors: 0,1/2,1/2;1/2,0,1/2;1/2,1/2,0

lattice_vectors: |
    a=1.8 c=10
    a*r3/2  a/2 0
    a*r3/2 -a/2 0
    0       0   c

In the last example, a substition is being performed, where the first line contains variable definitions.

One test this on the command line as follows:

$ pm-lattice --lattice-vectors '1 0 0 ; 0 1 0 ; 0 0 1' --print-attribute lattice_vectors
lattice_vectors:
  [[ 1.00000000,  0.00000000,  0.00000000],
   [ 0.00000000,  1.00000000,  0.00000000],
   [ 0.00000000,  0.00000000,  1.00000000]]

3 - Prototype Crystals

A collection of sample crystals.

In order to test out the code, it is useful to have sample crystals. At present, there is a script called pm-prototype-xtal which contains such data, and the information can be seen via tab completely print-attribute. This is only meant to be temporary until we have a more polished solution.

$ pm-prototype-xtal --print-attribute perovskite

lattice_vectors:
  [[ 3.91300000,  0.00000000,  0.00000000],
   [ 0.00000000,  3.91300000,  0.00000000],
   [ 0.00000000,  0.00000000,  3.91300000]]
basis_atoms:
  Sr: 
      [[ 0.50000000,  0.50000000,  0.50000000]]
  Ti: 
      [[ 0.00000000,  0.00000000,  0.00000000]]
  O: 
      [[ 0.50000000,  0.00000000,  0.00000000],
       [ 0.00000000,  0.50000000,  0.00000000],
       [ 0.00000000,  0.00000000,  0.50000000]]

4 - Symmetrizing atoms in crytal

A key task is to symmetrize the atoms such that they transform like irreducible representations.

Here we illustrate how to symmtrize displacements at a given q-point according to irreducible representations of the little group using the script pm-disp-qrep. Take the example of \(\bm{q}=(\frac{1}{2},\frac{1}{2},\frac{1}{2})\) in cubic SrTiO\(_3\). We will use pm-prototype-xtal to generate the crystal structure file.

$ pm-prototype-xtal --perovskite > xtal.yml

Printing out the irreducible representations, we have

$ pm-orbit-qrep -i xtal.yml --point-group Oh --qpoint 1/2,1/2,1/2 --print-irr-reps 

Orbit Key: ('Sr', 0), Atom Index: [0]
A2u
Orbit Key: ('Ti', 0), Atom Index: [0]
A1g
Orbit Key: ('O', 0), Atom Index: [0, 1, 2]
T1u

We can also print out the irreducible representation vectors.

$ pm-orbit-qrep -i xtal.yml --point-group Oh --qpoint 1/2,1/2,1/2 --print-irr-vectors

irr-vectors
Orbit Key: ('Sr', 0), Atom Index: [0]
A2u
('A2u', 0)
[[1.]]

Orbit Key: ('Ti', 0), Atom Index: [0]
A1g
('A1g', 0)
[[1.]]

Orbit Key: ('O', 0), Atom Index: [0, 1, 2]
T1u
('T1u', 0)
[[1. 0. 0.]
 [0. 1. 0.]
 [0. 0. 1.]]

5 - Symmetrizing displacements in Crystal

A key task is to symmetrize the basis such that the vectors transform like irreducible representations.

$ pm-prototype-xtal --perovskite > xtal.yml

Printing out the irreducible representations, we have

$ pm-disp-qrep -i xtal.yml --point-group Oh --qpoint 1/2,1/2,1/2  --print-irr-reps

('Sr', 0) [0]
T2g
('Ti', 0) [1]
T1u
('O', 0) [2 3 4]
A1g+Eg+T1g+T2g

We can also print out the irreducible representation vectors.

$ pm-disp-qrep -i xtal.yml --point-group Oh --qpoint 1/2,1/2,1/2 --print-irr-vectors

T2g[Sr]
 0.0000  0.0000  1.0000
 1.0000  0.0000  0.0000
 0.0000  1.0000  0.0000
T1u[Ti]
 1.0000  0.0000  0.0000
 0.0000  1.0000  0.0000
 0.0000  0.0000  1.0000
A1g[O]
 0.5774  0.0000  0.0000  0.0000  0.5774  0.0000  0.0000  0.0000  0.5774
Eg[O]
 0.7071  0.0000  0.0000  0.0000 -0.7071  0.0000  0.0000  0.0000  0.0000
-0.4082  0.0000  0.0000  0.0000 -0.4082  0.0000  0.0000  0.0000  0.8165
T1g[O]
 0.0000  0.0000  0.0000  0.0000  0.0000  0.7071  0.0000 -0.7071  0.0000
 0.0000  0.0000 -0.7071  0.0000  0.0000  0.0000  0.7071  0.0000  0.0000
 0.0000  0.7071  0.0000 -0.7071  0.0000  0.0000  0.0000  0.0000  0.0000
T2g[O]
 0.0000  0.7071  0.0000  0.7071  0.0000  0.0000  0.0000  0.0000  0.0000
 0.0000  0.0000  0.0000  0.0000  0.0000  0.7071  0.0000  0.7071  0.0000
 0.0000  0.0000  0.7071  0.0000  0.0000  0.0000  0.7071  0.0000  0.0000

This script will block diagonalize a dynamical matrix which has been provided. Consider the dyanmical matrix at the gamma point for STO:

$ cat dmat.yaml
dynamical_matrix_real: 
      3.6228  0       0      -2.990   0       0       0.2751  0       0       0.2751  0       0      -1.1822  0       0     
      0       3.6228  0       0      -2.990   0       0      -1.1822  0       0       0.2751  0       0       0.2751  0     
      0       0       3.6228  0       0      -2.990   0       0       0.2751  0       0      -1.1822  0       0       0.2751
     -2.990   0       0       2.060   0       0       0.2442  0       0       0.2442  0       0       0.4416  0       0     
      0      -2.990   0       0       2.060   0       0       0.4416  0       0       0.2442  0       0       0.2442  0     
      0       0      -2.990   0       0       2.060   0       0       0.2442  0       0       0.4416  0       0       0.2442
      0.2751  0       0       0.2442  0       0       4.0322  0       0       0.90    0       0      -5.460   0       0     
      0      -1.1822  0       0       0.4416  0       0      11.6616  0       0      -5.460   0       0      -5.460   0     
      0       0       0.2751  0       0       0.2442  0       0       4.0322  0       0      -5.460   0       0       0.90  
      0.2751  0       0       0.2442  0       0       0.90    0       0       4.0322  0       0      -5.460   0       0     
      0       0.2751  0       0       0.2442  0       0      -5.460   0       0       4.0322  0       0       0.90    0     
      0       0      -1.1822  0       0       0.4416  0       0      -5.460   0       0      11.6616  0       0      -5.4605
     -1.1822  0       0       0.4416  0       0      -5.460   0       0      -5.460   0       0      11.6616  0       0     
      0       0.2751  0       0       0.2442  0       0      -5.460   0       0       0.90    0       0       4.0322  0     
      0       0       0.2751  0       0       0.2442  0       0       0.90    0       0      -5.460   0       0       4.0322

We can then block diagonalize as follows:

pm-prototype-xtal --perovskite2 | pm-disp-qrep --point-group Oh --qpoint 0,0,0 --dynamical-matrix ~/dmat.yaml
T1u-block : [('T1u', 0), ('T1u', 1), ('T1u', 2), ('T1u', 3)]
Dynamical matrix sub-block - first row
[[ 0.    0.    0.    0.  ]
 [ 0.    2.57  3.2  -0.18]
 [ 0.    3.2   3.01 -1.33]
 [ 0.   -0.18 -1.33 16.7 ]]
Mass matrix sub-block - first row
[[ 36.7    5.59 -27.74   0.  ]
 [  5.59  45.08  13.87   0.  ]
 [-27.74  13.87  69.71   0.  ]
 [  0.     0.     0.    16.  ]]
Mass renormalized Eigvecs
[[-0.324  0.931 -0.169 -0.017]
 [ 0.692  0.111 -0.713  0.   ]
 [-0.644 -0.348 -0.68  -0.046]
 [-0.035  0.    -0.034  0.999]]
Unique Frequencies (meV)
[-8.19 -0.58 19.56 66.13]

T2u-block : [('T2u', 0)]
Dynamical matrix sub-block - first row
[[3.13]]
Mass matrix sub-block - first row
[[16.]]
Mass renormalized Eigvecs
[[1.]]
Unique Frequencies (meV)
[28.61]

It may be desirable to perform a unitary transformation within some irreducible representation subspace. Consider a yam file called unitary.yaml with the following content:

# unitary transformation to nearly diagonize the T1u subspace
- block: ['Optical',0] 
  irr_rep: 'T1u'
  instances: [0,1]
  U: 
    [[ -0.73059222, 0.68281403 ],
     [  0.68281403, 0.73059222 ]]

The conventional output is:

$ pm-prototype-xtal --perovskite2 | pm-disp-qrep --point-group Oh --qpoint 0,0,0  --print-vectors

('Acoustic', 0) [0, 1, 2, 3, 4]
T1u
('T1u', 0)
[[0.447 0.    0.    0.447 0.    0.    0.447 0.    0.    0.447 0.    0.    0.447 0.    0.   ]
 [0.    0.447 0.    0.    0.447 0.    0.    0.447 0.    0.    0.447 0.    0.    0.447 0.   ]
 [0.    0.    0.447 0.    0.    0.447 0.    0.    0.447 0.    0.    0.447 0.    0.    0.447]]
('Optical', 0) [0, 1, 2, 3, 4]
2T1u
('T1u', 0)
[[-0.224  0.     0.     0.894  0.     0.    -0.224  0.     0.    -0.224  0.     0.    -0.224  0.     0.   ]
 [ 0.    -0.224  0.     0.     0.894  0.     0.    -0.224  0.     0.    -0.224  0.     0.    -0.224  0.   ]
 [ 0.     0.    -0.224  0.     0.     0.894  0.     0.    -0.224  0.     0.    -0.224  0.     0.    -0.224]]
('T1u', 1)
[[-0.866  0.     0.     0.     0.     0.     0.289  0.     0.     0.289  0.     0.     0.289  0.     0.   ]
 [ 0.    -0.866  0.     0.     0.     0.     0.     0.289  0.     0.     0.289  0.     0.     0.289  0.   ]
 [ 0.     0.    -0.866  0.     0.     0.     0.     0.     0.289  0.     0.     0.289  0.     0.     0.289]]
('O', 0) [2 3 4]
T1u+T2u
('T1u', 0)
[[ 0.408  0.     0.     0.408  0.     0.    -0.816  0.     0.   ]
 [ 0.    -0.816  0.     0.     0.408  0.     0.     0.408  0.   ]
 [ 0.     0.     0.408  0.     0.    -0.816  0.     0.     0.408]]
('T2u', 0)
[[ 0.     0.     0.707  0.     0.     0.     0.     0.    -0.707]
 [-0.707  0.     0.     0.707  0.     0.     0.     0.     0.   ]
 [ 0.     0.     0.     0.    -0.707  0.     0.     0.707  0.   ]]

Now we can print the relevant output after the unitary transformation:

$ pm-prototype-xtal --perovskite2 | pm-disp-qrep --point-group Oh --qpoint 0,0,0  --unitary-transformation ~/unitary.yaml --print-vectors

('Optical', 0) [0, 1, 2, 3, 4]
2T1u
('T1u', 0)
[[-0.428  0.     0.    -0.653  0.     0.     0.36   0.     0.     0.36   0.     0.     0.36   0.     0.   ]
 [ 0.    -0.428  0.     0.    -0.653  0.     0.     0.36   0.     0.     0.36   0.     0.     0.36   0.   ]
 [ 0.     0.    -0.428  0.     0.    -0.653  0.     0.     0.36   0.     0.     0.36   0.     0.     0.36 ]]
('T1u', 1)
[[-0.785  0.     0.     0.611  0.     0.     0.058  0.     0.     0.058  0.     0.     0.058  0.     0.   ]
 [ 0.    -0.785  0.     0.     0.611  0.     0.     0.058  0.     0.     0.058  0.     0.     0.058  0.   ]
 [ 0.     0.    -0.785  0.     0.     0.611  0.     0.     0.058  0.     0.     0.058  0.     0.     0.058]]

Given some distorted crystal structure, one can project the displacement onto symmetrized displacements. Consider the primitive unit cell of STO where the ferroelectric mode is allowed to condense by treating the nuclear motion as classical:

$ cat xtal_ferro.yaml

# Crystal
vec:
  [[ 3.89736730,  0.00092044,  0.00092044],
   [ 0.00092044,  3.89736730,  0.00092044],
   [ 0.00092044,  0.00092044,  3.89736730]]
atoms:
  - Sr:
      [[ 0.02422827,  0.02422827,  0.02422827]]
  - Ti:
      [[ 0.52563170,  0.52563170,  0.52563170]]
  - O:
      [[ 0.51647453,  0.01719097,  0.51647453],
       [ 0.51647453,  0.51647453,  0.01719097],
       [ 0.01719097,  0.51647453,  0.51647453]]

Projecting onto irreducible representations gives:

pm-prototype-xtal --perovskite2 | pm-disp-qrep --point-group Oh --qpoint 0,0,0  --unitary-transformation unitary.yaml  --project-xtal xtal_ferro.yaml
Projection onto irreducible representations
Block : Acoustic
----------------
T1u     0.1744  0.1744  0.1744

Block : Optical
---------------
T1u     -0.0353 -0.0353 -0.0353
1.T1u   -0.0018 -0.0018 -0.0018

Block : O
---------
T1u     -0.0023 -0.0023 -0.0023
T2u     0       0       0

6 - Products of Irreducible Representations

Perform direct products and symmetric direct products of irreps.

A common group theoretical task is the direct product or symmetric direct product of irreducible representations. The composition of a product is obtained as

$ pm-irr_rep_product --point-group Oh --irr-reps T2g,T2g

# T2gxT2g  = A1g+Eg+T1g+T2g

The composition of a symmetric product is obtained as

$ pm-irr_rep_product --point-group Oh --irr-reps T2g,T2g --symmetric 

# [T2gxT2g] = A1g+Eg+T2g

An arbitrary number of irreps can be handled

$ pm-irr_rep_product --point-group Oh --irr-reps T2g,T2g,Eg,Eg,A2g

# T2gxT2gxEgxEgxA2g  = 2A1g+2A2g+4Eg+4T1g+4T2g

Another important task is constructing the irreducible representation vectors of the product representation in terms of the rows of the original irreducible representations.

$ pm-irr_rep_product --point-group Oh --irr-reps Eg,Eg  --print-irr-vectors  

#  EgxEg  = A1g+A2g+Eg
# 
# irr   Eg.0xEg.0  Eg.0xEg.1  Eg.1xEg.0  Eg.1xEg.1  
# A1g   0.7071     0.0        0.0        0.7071     
# A2g   0.0        0.7071     -0.7071    0.0        
# Eg.0  0.0        0.7071     0.7071     0.0        
# Eg.1  0.7071     0.0        0.0        -0.7071

The same can be done for the symmetric product

$ pm-irr_rep_product --point-group Oh --irr-reps Eg,Eg  --print-irr-vectors  --symmetric 

# [EgxEg] = A1g+Eg
#
# irr   Eg.0xEg.0  Eg.0xEg.1  Eg.1xEg.1  
# A1g   0.7071     0.0        0.7071     
# Eg.0  0.0        1.0        0.0        
# Eg.1  0.7071     0.0        -0.7071

It might also be useful to print out the transpose of the results, which can be done with the print-transpose flag:

$ pm-irr_rep_product --point-group Oh --irr-reps Eg,Eg  --print-irr-vectors  --symmetric --print-transpose 

# [EgxEg] = A1g+Eg
#
#           A1g     Eg.0    Eg.1    
# Eg.0xEg.0  0.7071  0.0000  0.7071 
# Eg.0xEg.1  0.0000  1.0000  0.0000 
# Eg.1xEg.1  0.7071  0.0000 -0.7071

In many cases, one is only concerned with the identity representation, and the flag only-print-identity will only print identity representations and will prune out any basis vectors that are not contained in the product:

$ pm-irr_rep_product --point-group Oh --irr-reps Eg,Eg  --print-irr-vectors  --symmetric --only-print-identity 

# [EgxEg] = A1g+Eg
# 
#     Eg.0xEg.0 Eg.1xEg.1 
# A1g  0.7071    0.7071

7 - pm-convert-id-main-to-dev

The main branch has a different set of phase conventions than the development branch, and the irreducible derivatives must be converted in order to use them on the development branch.

In order to extract the needed information from the main branch, checkout a branch that has the relevant scripts to dump the output.

# checout the relevant offshoot of main branch from github remote
$ git checkout dev/output_scripts

# from the top level, reinstall to access needed cli
$ pip install -e .

Locate the irreducible derivative file that needs to be converted, and then run the following script.

# on branch dev/output_scripts
$ pm-convert-id-hdf5-to-yaml irreducible_derivatives.hdf5

# output is --> irr_deriv_and_basis_main.hdf5

Returning to the development branch (dev/only_phonons), the generated file irr_deriv_and_basis_main.hdf5 is read by a script which will rotate the irreducible derivatives and output them in the relevant format.

# on branch dev/only_phonons
$ pm-convert-id-main-to-dev --hdf5-name irr_deriv_and_basis_main.hdf5

This script prints to standard out a yaml file containing all tags needed to run pm-phonons-via-irr-derivatives.

8 - pm-phonons-via-irr-derivatives

The phonon frequencies are computed from the irreducible derivatives. Various different levels of output are provided.

The following tags are required:

point_group
lattice_vectors
basis_atoms
quadratic_irr_derivatives

If there are complex irreducible derivatives, the imaginary part must be provided by the tag quadratic_irr_derivatives_imaginary. The code will print out a summary of the irreducible derivatives with varying levels of verbosity.

$ pm-phonons-via-irr-derivatives -i input.yaml --print-summary --verbosity long

There are several levels of verbosity that can be seen via tab completion.