Most key tasks can be performed from the command line, and here we document all such functionality.
This is the multi-page printable view of this section. Click here to print.
Command Line Functionality
- 1: General Information for CLI
- 2: Input tags
- 3: Array Parser
- 4: Prototype Crystals
- 5: Symmetrizing atoms in crytal
- 6: Symmetrizing displacements in Crystal
- 7: Crystal structure
- 8: Products of Irreducible Representations
- 9: pm convert-id-main-to-dev
- 10: pm phonons-via-irr-derivatives
1 - General Information for CLI
PM has a command line interface (CLI), named pm, to access the various capabilities PM,
generated using PM’s DataSchemer package.
For the most part, a given CLI option is associated with a class within PM.
As outlined below,
basic documentation about all commands can be obtained at the command line,
and therefore this website only provides individualized attention to
selected CLI options which are nontrivial.
The CLI is called pm, and should be followed by a command tag,
such as pm lattice, pm crystal, etc. All CLI commands can be seen
by using pm -h or via
tab completion
$ pm <TAB><TAB>
abinitio-output displaced-crystal lattice-ftg
cluster disp-qrep orbit-qrep
convert-id-main-to-dev file-hive phonons-via-irr-derivatives
crystal get-variable-doc point-group-viewer
crystal-format irr-rep-product prototype-xtal
crystal-ftg irr-rep-symmetric-product star-rep
crystal-variables kpoints-fsg tensor-irr-rep
crystal-viewer lattice
The options for a given CLI command can be seen using pm command -h.
Assuming that the python module
argcomplete has been installed and set up, all CLI options can also be seen
by typing the command name followed by - and pressing tab twice.
$ pm crystal -<TAB><TAB>
--basis-atoms --input-files --shift-atom
--convert-to-supercell --lattice-vectors --shift-into-cell
--degub --permute-atoms --shift-origin
-h --precision --strict-input
--help --print-attribute --use-cartesian-coordinates
-i --rotate-lattice-vectors
For options that have restricted inputs, tab completion will show valid choices:
$ pm crystal --print-attribute<TAB><TAB>
atom_names lattice_vectors_length reciprocal_vectors_angle
atoms_cartesian mass_vector reciprocal_vectors_length
atoms_species_map natoms reciprocal_volume
basis_atoms nspecies space_dim
center positions species
lattice_dimension positions_cartesian species_names
lattice_vectors precision species_to_elements
lattice_vectors_angle reciprocal_vectors volume
Executing -h will print out the command information
$ pm crystal -h
usage: pm crystal [-h] --basis-atoms ATOMS --lattice-vectors VEC [--shift-into-cell]
[--convert-to-supercell S] [--use-cartesian-coordinates] [--permute-atoms X]
[--shift-origin X] [--rotate-lattice-vectors O] [--shift-atom AMP]
[--precision N] [--degub] [--input-files FILE [FILE ...]] [--strict-input]
[--print-attribute ATTR [ATTR ...]]
Exposes the Crystal class, allowing the basic properties of a crystal to be constructed.
options:
-h, --help show this help message and exit
--basis-atoms ATOMS (required) Basis atoms of the crystal structure.
--lattice-vectors VEC
(required) Lattice vectors in three dimensions, stored in a
matrix \(\hat a\).
--shift-into-cell Shift atoms such that they are within the conventional unit cell.
Entering the command without any options will print out the missing required arguments:
$ pm crystal
User Error: Must provide values for:
basis_atoms, lattice_vectors
Input tags can be provided on the command line, or they can be specified in yaml format
from standard input
or a file via the --input-file or -i tag.
Standard input is specified as - and an input file is given by name, such
as
$ pm crystal -i -
$ pm crystal -i input.yaml
Multiple input files can be specified, and can be mixed with standard input.
$ pm crystal -i input1.yaml input2.yaml
$ pm crystal -i - input1.yaml input2.yaml
2 - Input tags
List of Input Tags
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
3 - Array Parser
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 input parser which allows substantial flexibility to facilitate this (see PM’s DataSchemer package if interested in the details).
Consider entering the lattice vectors tag. All of the below are valid syntax. The parser expects 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 can test this on the command line as follows:
$ pm lattice --lattice-vectors '2.8 0 0 ; 0 2.8 0 ; 0 0 2.8' --print-attribute lattice_vectors
lattice_vectors:
[[2.8, 0 , 0 ],
[0 , 2.8, 0 ],
[0 , 0 , 2.8]]
PM accepts several abbreviations when specifying an array as input: I, FCC, and BCC. Additionally, each abbreviation can be preceded by 1, 2, 3, or 4, which simply multiplies each array by the corresponding integer. For example:
$ pm lattice --lattice-vectors 2BCC --print-attribute lattice_vectors
lattice_vectors:
[[-2, 2, 2],
[ 2, -2, 2],
[ 2, 2, -2]]
4 - Prototype Crystals
In order to test out the code, it is useful to have sample crystals. At present, there is a command pm prototype-xtal which contains such data, and the information can be seen via tab completing 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]]
5 - Symmetrizing atoms in crytal
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.]]
6 - Symmetrizing displacements in Crystal
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 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
7 - Crystal structure
Interfaces to Crystal class.
$ pm prototype-xtal --print-attribute perovskite | pm crystal -i -
8 - Products of Irreducible Representations
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
9 - pm convert-id-main-to-dev
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.
10 - pm phonons-via-irr-derivatives
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.