common_caseutil.ConvertCartesianToInnerCoord(fCell, listCart)

Convert cartesian to inner coordinate in specific lattice

Parameters:

• fCell – a 3x3 ndarray, each row is a vector of lattice axis
• listCart – a list of Cartesian coordinate

common_caseutil.ConvertCartesianToLattice(listBravis, nLatticeType=0)

Convert Bravis matrix to 3 parameter + 3 angle

Parameters:

• listBravis – Bravis matrix
• nBravis – represent bravis type, will convert primitive lattice to convetional lattice according to this.

common_caseutil.ConvertInnerCoordToCartesian(fCell, listInner)

Convert inner coordinate to cartesian coordinate in specific lattice

common_caseutil.ConvertLatticeToCartesian(fLatticeParameter, fLatticeAngle)

Convert lattice parameter+angle to Bravis matrix( Numpy array )

Parameters:fLatticeAngle – should in unit of degree

exception common_caseutil.FormatError(value)

Represent file format incorrect

common_caseutil.GetDefaultCharge(nIndex)

Give a default Charge for specific atom index

class common_caseutil.KPointsT(stFile=None)

Represent a set of kpoints Contains k-point coordinate, k-point name

ConvertUnit(stModeNew, mLatt=None)

Convert k-points coordinate between crystal,cartesian and tpiba unit based on structure Note this conversion mostly only appeared in orthogonal lattice, as in practice, non-orthogonal lattice never use tpiba unit. Equation : matLattVec . vecCrystal = vecCartesian

Parameters:

• stModeNew – the new k-point unit
• mLatt – the real-space lattice vector that k-point is based on; note for some program it is primitive lattice ( like VASP and YAehmop ), and others are conventional lattice (Wien2K cubic). If None is used, we use conventional lattice for tpiabc (which belongs to Wien2K cubic) and primitive for others.

Returns:

whether the conversion completed

CreateFromPointLine(listK2, listPointsCount=None, nTotal=None, mLatt=None, nDivisor=None)

Read k-point from x,y,z + point along the line format kpt must be in formar [x,y,z], [x,y,z,name] or [name,x,y,z] The mode is not changed during this process

Parameters:

• listK2 – the list of k-points in KPointsT readable format
• listPointsCount – the number of points along each line
• nTotal – the total number of points. The lattice must be specified if use this option, and k-points will be spread homogeneously along lines
• mLatt – the lattice vectors for k-points, necessary if k-points is in internal coordinate
• nDivisor – if this number is set, then number of points along each line must be a divisor/factor of this number. This function is especially useful for WIEN2k. Set to 0 means the program will automatically choose a number.

Returns:

the divisor

CreateKPointsFromSymmetry(nGroup)

Create high-symmetry k-points list from spacegroup symmetry The lattice must be set before invoke this function

Parameters:nGroup – the 230 space group index (1-230)

GetTurningPoint()

Return index of turning points in the k-point path Start point and end point are not included Index start from 0

Warning: sometimes a band structure may contains duplicated points (like band-mode in VASP), which is bad so we skip such k-points

ReadFromFile(stFileName)

Read k-point from a file in raw format format as first line is k-point data mode; if it is not “crystal”/”cartesian”/”tpiba”/”piba”, then it is set to crystal and this line is used as k-point each k-point format ( “,” means space or tab ) * [name],kx,ky,kz,[weight] * kx,ky,kz,[name] * kx,ky,kz,weight,[name] name must start with character and no space in it; if it start with number, then it is treated as kx!

ReadFromList(list_kp)

Create object from simple k-point list in format [ [x1,y1,z1] …] or [ [x1,y1,z1,w1] …] or [ [name,x1,y1,z1,w1] …] The unit is not concerned in this case

WriteToFile(stFileName, bWriteName=False, bWriteWeight=False)

Write k-point list to a file with/without

Parameters:bUseName – write name or not, default no

get_k_xaxis()

Get a list of points on one axis for band structure plotting

If two points are two far away, then they are treated as seperated, the distance between them is eliminated

:return:list_x and list_name for x-axis and k-point names, list_break for the index of k-points where a new kpath starts

class common_caseutil.Lattice

A basic representation of lattice, all basic number unit in bohr and deg Cartesian vectors follow this: c-axis as [0,0,c] b-c in a plane of axis Members start with “Create” will return a new Lattice object, otherwise itself will change

AddAtom(listPos, unit='bohr', latt='primitive', a=None)

Add a atom list by Cartesian Coordinate or Crystal Coordinate, indicated by unit_length Note: please be cautious with latt=”alat”, because “a” is not fixed during cell shape change.

Parameters:

• listCart – in form of [Element name,x,y,z]
• unit – indicate type of xyz : bohr, ang/angstrom, cry/crys/crystal, alat
• latt – indicate which cell xyz is related to : primtive/conventional ( only affect when unit is crystal ), raw ( stored cell vectors )
• a – the length of a in unit of Bohr. Default is the fLatticeLength (which is the first lattice vector if bRaw, otherwise conventional lattice vector).

AddAtomFromCartesian(listCart)

Add a atom list by Cartesian Coordinate

Parameters:listCard – a list of atom positions, each atom positions must be in the format [‘Name’,x,y,z]

ChangeCell(stMode='c:1')

Change a specific Lattice object with specific method Note: any change on crystal axis will not affect the internal coordinate of atom In clayer mode, if there exist a distance much larger than others, it will be treated as Slab vacuum and not extended

Params stMode:the way to change lattice, “c” and “tmdc” is supported. in format “mode:para;mode:para”

CheckAtom()

Check whether an Atom is < 0 or > 1, or there are duplicated atoms

ConventionalCellVector

Conventional cell vectors

CorrectError()

Set some standard fractional coordinate (like 1/3 ) to their exact value to beautify the output Example : 0.6666663562472133 to 0.6666666666667, 0.249999998232 to 0.25

CreateSlab(dThreshold=-1.0, nLatt=7, nVacuum=5, nFix=3, nShift=0)

Slice a n-layer slab from bulk cell with v layer vacuum along c axis. The atoms will be placed in the middle of the cell. A layer ( Unit layer ) is a combination of continuious atom layer. An atom layer is all atom in same c internal coordinate. Unit layer doesn’t require to be same between each two. For example, MoS2 is a layer structure, and a layer contains S-Mo-S, 3 atom layers In AB stack, A is both an atom layer and an unit layer. B is another. repeat 5 times will create a A B A B A slab. Shift = 1 create B A B A B slab.

Parameters:

• nUnitLayer – the mono atom layer count in one unit layer in this manipulation. ( not used currently)
• nLatt – the layer counts of unit layer.
• nVacuum – the layer of vacuum.
• nFix – the layer of atom never move ; the fixed indexs will be returned as return value
• nShift – the start layer, counting from
• dThreshold – The minimum distance between 2 layer. Auto detect if < 0. For example, all atom in range of 4 bohr is treated as same atom layer ( van der Waals ). For a ionic crystal, it should less than 0.1.

CreateSurfCell(stRefAxis='001', dRot=0, mRot=[[1, 0], [0, 1]])

Slice a cell that have a plance perpendicular to specifc stRefAxis ( for surface model ) The input miller index should be simlified, like 002 may cause unexpected result

ExpandCell(stRefAxis='001', nCell=1, nVacuum=1)

Then extended Cell x times plus vacuum y times of original cell. Some high symmertry may broke for this reason.

Parameters:

• stRefAxis – the axis to extended ( always postive ), only 100,010 and 001 is supported
• nCell – the number of cell layer
• nVacuum – the length of vacuum layer ( relative to cell length )

GetAtomList(unit='bohr', latt='primitive', extend=[0, 0, 0, 0, 0, 0])

Get a list of atom in some representaion

Parameters:

• unit – the unit of coordinate, including bohr,ang,alat,primitive,conventional
• latt – the atom in whole convetional cell or one primitive cell
• extend – the lattice will be examed

GetLayerAtom(dThreshold=-1.0)

Get atom layer along c axis

Parameters:dThreshold – The minimum distance between 2 layer. Auto detect if < 0. For example, all atom in range of 4 bohr is treated as same atom layer ( van der Waals ). For a ionic crystal, it should less than 0.1.

IsRaw

Return whether Lattice object is operated in raw mode

MoveCell(vDistance=[0, 0, 0])

Move Cell by a specific vector

Parameters:

• vDistance – The vector to move, unit of crystal coordinate of conventional vector
• nAtomIndex – which atom to move, if not set vector will be used, vector will be neglected otherwise
• nNewPos – Which position the atom will be moved to

PrimitiveCellVector

Primitive cell vectors

ReadFromPrimitiveCellVector(mBravis, nLatticeType=None)

Read Cell from cell vectors and Lattice Type ( If no lattice type is used, original one will be used) Atoms’ crystal coordination will not moved !

Parameters:

• mBravis – Cell vectors
• nLatticeType – The lattice type, if NONE then the nLatticeType stored in the current object is used
• bRaw – If set to true, will not utilize primitive-conventional convertion in the process, and put the mode of Lattice object to raw

ReadFromRawCellVector(mBravisConv, mBravisPrim=None)

Read Lattice object from specified cell vectors Note one may provide BOTH conventional and primitive cell vectors

Parameters:

• mBravisConv – Bravis matrix of the conventional cell
• mBravisPrim – Bravis matrix of the primitive cell, optional; If negelected Conv/Prim are the same.

RotateCell(arRefPoint=[0, 0, 0], stRefAxis='001', stNewAxis='001')

Transform a cell to another orientation ( for surface SLAB ) Fix ref point, rotate ref axis (a or b or c) to new orientation, xyz axis will be rotated as well Equally = all atom rotate reverse

Note: the rotation axis is vertical to the plane of old ref axis and new axis All action is do in conventional cell.

ShowSummary(stFileName=None)

Write cell information to specific file or screen

Parameters:stFileName – if set to None, set print to screen

Volume

Volume of convetional cell vectors

init_fix(b_fix=False)

Create informations about fix

Parameters:b_fix – initialze with True or False

listAtomCartesian

list all atom in Cartesian Coordinate

listAtomInConvCell

List all atom in the conventional cell ( by conventional cell crystal coordinate )

listFix = None

list of where atoms are fixed on given direction

classmethod load_xml(filename)

Load parameters from a XML file

save(filename)

Save parameters to a XML file

class common_caseutil.NamelistIO(pre_line=None)

A Class used for Fortran namelist like file I/O Warning: This invokes exec on lines directly, please use with caution!

AddValue(part, name, value)

Add a name=value contained in specific &part/

ReadFromFile(stFileName)

Read content from one file in Fortran namelist format

WriteToFile(stFileName)

Write content to one file in Quantum-Espresso readable format

static default_pre_line(line)

Treat all “!” as the starting point of a comment Remove all redundant blanks and comments This is used when pre_line is None @todo we don’t check if it is inside a string

class common_caseutil.RawFileIO(filename=None)

A class represents a files which can be used for IO It keeps exactly every line in the file, and won’t lost anything between I/O, but still support value edit and addition (“n” is stored) It is suitable to edit files that have large parts not concerned by us, but should not be modified, and it is not worth to encode a full I/O for it. Its efficiency is a hell but still always faster than QM calculation so do not bother it.

edit_name_value(name, value)

Edit name = value type string if name does not exist, then add one

edit_value(ix_line, value, pos_end=None, name=None)

Edit the value in the line, assuming only one value is presented in the line there are several way to guess it: 1. after first “=” 2. first number if pos_end is used then look for the position if name is used then look for the name

Parameters:

• ix_line – the line index which to be edited
• value – the value which should be set
• pos_end – the end position of the value which is to be set
• name – the value just after name will be set ( possibly skip a “=” )

find_marked_line(mark, num_shift=0, ix_start=None)

Get the index of line, with specific number of lines before/after its line

Parameters:

• mark – the string which the first appear should be found
• num_shift – the i-th line after the marked line(can be 0 or negative)
• ix_start – which line the search should start, start at 0

Returns:

the line index, if not found return 0

read(filename)

Read a file

write(filename)

Write to a file

common_caseutil.ReadSplitLine(fIn, stSep='')

Read a line from file and split it by default ( no EOL and ignore empty), or split with specific string

common_caseutil.debug_print(level, *para)

print for debug, logLevel can be used to control whether output

common_caseutil.deprecated(func)

This is a decorator which can be used to mark functions as deprecated. It will result in a warning being emitted when the function is used.

common_caseutil.f_CorrectFloat(dIn, dErrMax=1e-06)

make a float number reach the most exact value ( like 60.00000001 to 60 ) also make it reach 1/6, 1/5, 1/4 , 1/3 1/2 and so on

Parameters:

• dIn – The number to be detect and modify, or an array ( every number in it will be modified)
• dErrMax – The error can be treated as floating point error

Returns:

0 if not found, otherwise x in 1/x

common_caseutil.f_Data_ReadMultiCol(stFileName, stComment='#', func=None)

Read data from multi-columns data

Parameters:

• stComment – If a line start with this character, then treat it as comment
• func – the function to convert each element string to specific object

common_caseutil.f_Data_ReadTwoCol(stFileName, stComment='#', func=None)

Read data from empty line seperated two-columns data, which can be read directly by xmgrace This function require all sets in the file must have same number of rows

Parameters:stComment – If a line start with this character, then treat it as comment Returns:a list of rows

common_caseutil.f_Data_Write(list_data, filename, b_col=False, b_twocol=False, b_complex=False, b_split=True)

This function can write data into files in the two-columns or the multi-columns format. The data is a nested lists, can be row first or column first.

Parameters:

• list_data – list of [x,y1,y2,y3…]
• b_col – the data is in the format of [[x,x,x…],[y1,y1,y1]…
• b_twocol – write the data in two-columns format instead of [x,y1,y2..] format
• b_split – write all real parts of y first and then imaginary parts: x,y1.real,y2.real,…y1.imag,y2.imag…
• b_complex – can be used when the data is complex, the real and imaginary parts will be in different columns

common_caseutil.f_Data_WriteMultiCol(data, stFileName, delim=' ', func=None)

Write data into multi-columns with space seperated

Parameters:

• data – 2-D list contains the data
• stFileName – the output filename
• func – the function to convert element to string. If not specified, set to str()

common_caseutil.f_Data_WriteTwoCol(data, stFileName)

Write data to empty line seperated two-columns data, which can be read directly by xmgrace

common_caseutil.f_File_GetLibraryPath()

Get the path of python library file itself

common_caseutil.f_File_IsNullOrEmpty(st)

Determine whether a file does not exist, or is empty

common_caseutil.f_FindFraction(dIn, dErrMax=1e-06, dMaxDiv=10)

Find the most appraoching fraction for given float number

Parameters:

• dIn – the floating number
• dErrMax – the relative maximum error allowed between fraction and dIn
• dMaxDiv – the maximum divider allowed

Returns:

two integer to represent the fraction. If not found, return two None

common_caseutil.f_FindGCD(n1, n2)

Find the greatest common divisor of two integers

common_caseutil.f_FindLCM(n1, n2)

Find the least common multiple of two integers

common_caseutil.f_GetCaseName()

Get current folder name, used in Wien2K as casename

common_caseutil.f_GetExecFullPath(stExe)

Get a program full path

common_caseutil.f_GetLibDataPath()

Get PYTHONPATH for read some data file in the path

common_caseutil.f_GetReciprocalLattice(matR)

Get reciprocal lattice vectors from real lattice or vice versa Recprocal lattice is just inversion of real lattice * 2pi, indeed.

common_caseutil.f_GetSurfaceFromMiller(list_index)

Get three vectors ( base cell vectors ) perpendicular to specific miller index :return: first two make the surface , the third make it a cell

common_caseutil.f_IsNumber(stInput)

Detect if this string can be converted to a float number, return true or false

common_caseutil.f_Latt_IsClinic(listAngle)

Determine whether a cell is monoclinic or tricilinic

common_caseutil.f_MaxCommonSubmultiple(a, b)

return maximum common submultiple of two integer

common_caseutil.f_MinCommonMultiple(a, b)

return minimum common multiple of two integer

common_caseutil.f_ReadFileFloatValue(stFileName)

Read a single floating point value of one file If the file does not exists, then return None

common_caseutil.f_ReadFileIntValue(stFileName)

Read a single integer point value of one file If the file does not exists, then return None

common_caseutil.f_ReadStdout(cmd)

Open a Shell with specific command and return its stdout

common_caseutil.f_RotateMatrix(dAngle, vec)

Create a rotation matrix from angle and vector ( vector will be convert to unit vector )

common_caseutil.f_SolveCross(s1, s2, s3)

Find minimum integer solution for UxV = nS

common_caseutil.f_Split_EnumerateRangeString(stRange, stRangeType='mms')

Generate a list of all possible combination from a string string format : PropertyA:20,40,50~100~10;PropertyB_x:4~12~2 “_x” after name means relative value ( used for ecutrho, which is relative to ecutwfc) relative value will be set in the order of string, if ecutrho_x is before ecutwfc, it will be used as ecutwfc in original input file * parameter

common_caseutil.f_Split_RangeString(stRange, stRangeType='mms')

Generate a list of number from string. String format: a,b,c,d~e~f,h,… ( every character represent a float value) ‘,’ seperate different value ‘a~b~c’ define a list of a,a+c,a+2*c,…a+n*c, until a+n*c > b ( if a <b) or a+n*c < b ( if a > b) which means 1~3~1 -> 1,2,3 if a contains non-digit character, the value will be stored as string if “~” is used, the value will be stored as float; otherwise string

Parameters:

• stRange – the string you wanna to split
• stRangeType – define what a~b~c represent , ‘mms’ means min-max-step, ‘msm’ means min-step-max

common_caseutil.f_WriteFileFloatValue(val, stFileName)

Write a single floating point value to one file

common_caseutil.f_WriteFileIntValue(val, stFileName)

Write a single integer value to one file

common_caseutil.f_env_GetJobSystem()

Get Job Management System Name

common_caseutil.f_env_MpirunCommand(stCommand, nProcessIn=0, stJobSystem=None)

create a string to run command with mpirun if enviroment varialbe tmckit_serial = 1, then mpirun will not be used ( depreceted ) if nProcess = 0 and enviroment varialbe tmckit_process is set, then use $tmckit_process as nProcess will be used

Parameters:

• stCommand – The main command used after mpirun
• nProcess – The count of process. If not used or set as 0, default to hostfile
• stJobSystem – Specify Job Management System. If not used, default as auto detect. If no job system detected, the command will be used directly.

common_caseutil.f_env_RunMpirunCommand(stCommand, nProcess=0, stJobSystem=None)

run command with mpirun

common_caseutil.f_file_ensure_no_file(filename)

Test whether a file exists. If yes then delete it.

common_caseutil.f_file_ensuredir(dirname)

Test whether a directory exists. If not then create it.

Parameters:dirname – the directory to create. If it is empty or None, then set to current directory Returns:the diretory path guaranteed to work

common_caseutil.f_write_file_string(val, filename)

Write a single string to one file