Manual¶

The complete WESTpy reference is reported below.

Units¶

Westpy uses Hartree atomic units.

class westpy.units.Units(*args, **kwargs)¶

Bases: dict

Dictionary for units that supports .attribute access.

westpy.units.set_units()¶

Sets Rydberg atomic units.

Available units are:

Bohr
Angstrom, Ang
Rydberg, Ry
Hartree, Ha
eV

Note

westpy operates in Rydberg atomic units.

Utilities¶

Set of utilities.

westpy.utils.bool2str(logical)¶

Converts a boolean type into a string .TRUE. or .FALSE. .

Parameters: logical (boolean) – logical
Returns: .TRUE. or .FALSE.
Return type: string
Example

>>> from westpy import * 
>>> t = bool2str(True)
>>> f = bool2str(False)
>>> print(t,f) 
.TRUE. .FALSE.

westpy.utils.convertYaml2Json(fyml, fjson)¶

Converts the file from YAML to JSON.

Parameters

fyml (string) – Name of YAML file
fjson (string) – Name of JSON file

Example

>>> from westpy import * 
>>> convertYaml2Json("file.yml","file.json") 

Note

The file fjon will be created, fyml will not be overwritten.

westpy.utils.download(url, fname=None)¶

Downloads a file from url.

Parameters

url (string) – url
fname (string) – file name, optional

Example

>>> from westpy import * 
>>> download("http://www.west-code.org/database/gw100/xyz/CH4.xyz")

Note

The file will be downloaded in the current directory.

westpy.utils.extractFileNamefromUrl(url)¶

Extracts a file name from url.

Parameters: url (string) – url
Returns: file name
Return type: string
Example

>>> from westpy import * 
>>> extractFileNamefromUrl("http://www.west-code.org/database/gw100/xyz/CH4.xyz")

westpy.utils.gaussian(x, mu, sig)¶

return normal distribution at point x.

\(f(x;\mu,\sigma) = \frac{1}{\sigma\sqrt{2\pi}}e^{-\frac{(x-\mu)^2}{2\sigma^2}}\)

Parameters

x (float) – x
mu (float) – \(\mu\)
sigma (float) – \(\sigma\)

Returns

\(f(x;\mu,\sigma)\)

Return type

float

Example

>>> from westpy import * 
>>> gaussian(1.0,2.0,3.0)

westpy.utils.listLinesWithKeyfromOnlineText(url, key)¶

List lines from text file located at url, with key.

Parameters

url (string) – url
key (string) – key word

Returns

list of lines

Return type

list

Example

>>> from westpy import * 
>>> url = "http://www.quantum-simulation.org/potentials/sg15_oncv/upf/Si_ONCV_PBE-1.1.upf"
>>> key = "z_valence"
>>> l = listLinesWithKeyfromOnlineText(url,key)
>>> print(l) 
['       z_valence="    4.00"'] 

Note

Can be used to grep values from a UPF file.

westpy.utils.listValuesWithKeyFromOnlineXML(url, key)¶

List values from XML file located at url, with key.

Parameters

url (string) – url
key (string) – key word

Returns

list of values

Return type

list

Example

>>> from westpy import * 
>>> url = "http://www.quantum-simulation.org/potentials/sg15_oncv/xml/Si_ONCV_PBE-1.1.xml"
>>> key = "valence_charge"
>>> l = listLinesWithKeyfromOnlineXML(url,key)
>>> print(l) 
['4'] 

Note

Can be used to grep values from a XML file.

westpy.utils.readJsonFile(fname)¶

Reads data from file using the JSON format.

Parameters: fname (string) – file name
Returns: data
Return type: dict/list
Example

>>> from westpy import * 
>>> data = readJsonFile("mass.json") 

Note

The file will be read from the current directory.

westpy.utils.read_cube(fname)¶

Read cube file into numpy array

params:: fname: filename of cube file

returns: (data: np.array, metadata: dict)

westpy.utils.read_imcube(rfname, ifname='')¶

Convenience function to read in two cube files at once, where one contains the real part and the other contains the imag part. If only one filename given, other filename is inferred.

params:: rfname: filename of cube file of real part ifname: optional, filename of cube file of imag part

returns: np.array (real part + j*imag part)

westpy.utils.writeJsonFile(fname, data)¶

Writes data to file using the JSON format.

Parameters

fname (string) – file name
data (dict/list) – data

Example

>>> from westpy import * 
>>> data = {}
>>> data["mass"] = 1.0
>>> writeJsonFile("mass.json",data) 

Note

The file will be generated in the current directory.

westpy.utils.write_cube(data, meta, fname)¶

Write volumetric data to cube file along

params:

data: volumetric data consisting real values meta: dict containing metadata with following keys:

atoms: list of atoms in the form (mass, [position])

org: origin

xvec,yvec,zvec: lattice vector basis

fname: filename of cubefile (existing files overwritten)

returns: None

westpy.utils.write_imcube(data, meta, rfname, ifname='')¶

Convenience function to write two cube files from complex valued volumetric data, one for the real part and one for the imaginary part. Data about atoms, origin and lattice vectors are kept same for both. If only one filename given, other filename is inferred.

params:

data: volumetric data consisting complex values meta: dict containing metadata with following keys

atoms: list of atoms in the form (mass, [position])

org: origin

xvec,yvec,zvec: lattice vector basis

rfname: filename of cube file containing real part ifname: optional, filename of cube file containing imag part

returns: None

Atom¶

class westpy.atom.Atom(symbol='X', position=(0, 0, 0), units=1.0)¶

Bases: object

Class for representing a single atom.

Parameters

symbol (string) – chemical symbol
position (3-dim tuple) – position
units ("Bohr" or "Angstrom") – Units, optional

Example

>>> from westpy import * 
>>> atom = Atom("Si",(0.,0.,0.))

Note

Positions are set in a.u. by default. If you set units=Angstrom a coversion to a.u. will be made.

Bohr = 1.0¶

Geometry¶

class westpy.geometry.Geometry(cell=None)¶

Bases: object

Class for representing a set of atoms in a periodic cell.

Example

>>> from westpy import * 
>>> geom = Geometry()
>>> geom.setCell( (1,0,0), (0,1,0), (0,0,1) ) 
>>> geom.addAtom( "Si", (0,0,0) ) 
>>> geom.addSpecies( "Si", "http://www.quantum-simulation.org/potentials/sg15_oncv/upf/Si_ONCV_PBE-1.1.upf" ) 

Note

Vectors are set in a.u. by default. If you set units=Angstrom a coversion to a.u. will be made.

Bohr = 1.0¶

addAtom(symbol, position, units=1.0)¶

Adds a single atom.

Parameters

symbol (string) – chemical symbol
position (3-dim tuple) – position
units ("Bohr" or "Angstrom") – Units, optional

Example

>>> from westpy import * 
>>> geom = Geometry()
>>> geom.addAtom( "Si", (0,0,0) ) 

addAtomsFromOnlineXYZ(url)¶

Adds atoms from XYZ file (only one image) located at url.

Parameters: url (string) – url
Example

>>> from westpy import * 
>>> geom = Geometry()
>>> geom.addAtomsFromOnlineXYZ( "http://www.west-code.org/database/gw100/xyz/CH4.xyz" ) 

addAtomsFromXYZFile(fname)¶

Adds atoms from XYZ file (only one image).

Parameters: fname (string) – file name
Example

>>> from westpy import * 
>>> geom = Geometry()
>>> geom.addAtomFromXYZFile( "CH4.xyz" ) 

addFracCoordAtom(symbol, frac_coord)¶

adds a single atom by fractional coords :param symbol: chemical symbol :type symbol: string :param position: position :type position: 3-dim tuple

Example

>>> from westpy import *
>>> geom = Geometry()
>>> geom.addFracCoordAtom( "Si", (0,1/3.0,2/3.0) )

addSpecies(symbol, url)¶

Adds a species.

Parameters

symbol (string) – chemical symbol
url (string) – url

Example

>>> from westpy import * 
>>> geom = Geometry()
>>> geom.addSpecies( "Si", "http://www.quantum-simulation.org/potentials/sg15_oncv/upf/Si_ONCV_PBE-1.1.upf" ) 

Note

You can use this method to add either upf or xml pseudopotentials. However it is forbidded to mix them.

downloadPseudopotentials()¶

Download Pseudopotentials.

Example

>>> from westpy import * 
>>> geom = Geometry()
>>> geom.addAtomsFromOnlineXYZ( "http://www.west-code.org/database/gw100/xyz/CH4.xyz" )
>>> geom.addSpecies( "C", "http://www.quantum-simulation.org/potentials/sg15_oncv/xml/C_ONCV_PBE-1.0.xml")
>>> geom.addSpecies( "H", "http://www.quantum-simulation.org/potentials/sg15_oncv/xml/H_ONCV_PBE-1.0.xml")
>>> geom.downloadPseudopotentials()

Note

Pseudopotential files will be downloaded in the current directory.

getNumberOfAtoms()¶

Returns number of atoms.

Returns: number of atoms
Return type: int
Example

>>> from westpy import * 
>>> geom = Geometry()
>>> geom.addAtomsFromOnlineXYZ( "http://www.west-code.org/database/gw100/xyz/CH4.xyz" )
>>> nat = geom.getNumberOfAtoms()
>>> print( nat ) 
5 

getNumberOfElectrons()¶

Returns number of electrons.

Returns: number of electrons
Return type: int
Example

>>> from westpy import * 
>>> geom = Geometry()
>>> geom.addAtomsFromOnlineXYZ( "http://www.west-code.org/database/gw100/xyz/CH4.xyz" )
>>> geom.addSpecies( "C", "http://www.quantum-simulation.org/potentials/sg15_oncv/xml/C_ONCV_PBE-1.0.xml")
>>> geom.addSpecies( "H", "http://www.quantum-simulation.org/potentials/sg15_oncv/xml/H_ONCV_PBE-1.0.xml")
>>> nelec = geom.getNumberOfElectrons()
>>> print( nelec ) 
8

getNumberOfSpecies()¶

Returns number of species.

Returns: number of species
Return type: int
Example

>>> from westpy import * 
>>> geom = Geometry()
>>> geom.addAtomsFromOnlineXYZ( "http://www.west-code.org/database/gw100/xyz/CH4.xyz" )
>>> ntyp = geom.getNumberOfSpecies()
>>> print( ntyp ) 
2 

isValid()¶

Checks if geometry is valid

The method checks that:

the cell is set
at least one atom has been added
the pseudopotentials of all species are defined
the pseudopotentials do not contain a mix of upf and xml formats

setCell(a1=(0, 0, 0), a2=(0, 0, 0), a3=(0, 0, 0), units=1.0)¶

Sets cell, given the three vectors \(a_1\), \(a_2\), \(a_3\).

Parameters

a1 (3-dim tuple) – \(a_1\)
a2 (3-dim tuple) – \(a_2\)
a3 (3-dim tuple) – \(a_3\)
units ("Bohr" or "Angstrom") – Units, optional

Example

>>> from westpy import * 
>>> geom = Geometry()
>>> geom.setCell( (1,0,0), (0,1,0), (0,0,1) ) 

view(style='stick', width=800, height=800, ix=1, iy=1, iz=1, debug=False)¶

Display simulation box geom in Angstrom. ix, iy, iz is the perodic display to system style can be line, stick, sphere.

Parameters

style –
width –
height –
ix –
iy –
iz –
debug –

Returns

Ground State¶

class westpy.groundState.GroundState(geom, xc, ecut)¶

Bases: object

Class for representing a ground state calculation with DFT.

Parameters

geom (Class(Geometry)) – geometry (cell, atoms, species)
xc (string) – exchange-correlation functional
ecut (float) – energy cutoff for the wavefunction (in Rydberg units)

Example

>>> from westpy import * 
>>> geom = Geometry() 
>>> geom.setCell( (1,0,0), (0,1,0), (0,0,1) ) 
>>> geom.addAtom( "Si", (0,0,0) ) 
>>> geom.addSpecies( "Si", "http://www.quantum-simulation.org/potentials/sg15_oncv/upf/Si_ONCV_PBE-1.1.upf" ) 
>>> gs = GroundState(geom,"PBE",30.0)

Note

Vectors are set in a.u. by default. If you set units=Angstrom a coversion to a.u. will be made.

downloadPseudopotentials()¶

Download Pseudopotentials.

Example

>>> gs.downloadPseudopotentials()

Note

Pseudopotential files will be downloaded in the current directory.

generateInputPW(fname='pw.in')¶

Generates input file for pwscf. Valid only for QuantumEspresso calculations.

Parameters: fname (string) – fname, optional
Example

>>> gs.generateInputPW("pw.in") 

generateInputQbox(fname='qbox.in')¶

Generates input file for qbox. Valid only for Qbox calculations.

Parameters: fname (string) – fname, optional
Example

>>> gs.generateInputQbox("qbox.in") 

setCollinearSpin(tot_magnetization=0.0)¶

Sets collinear spin.

Parameters: tot_magnetization (float) – Total majority spin charge - minority spin charge, optional
Example

>>> gs.setCollinearSpin() 

setIsolated()¶

Sets isolated system. Valid only for QuantumEspresso calculations.

Example

>>> gs.setIsolated() 

setKmesh(kmesh)¶

Sets the uniform grid for k-points sampling.

Parameters: kmesh (3-dim tuple of int) – kmesh
Example

>>> gs.setKmesh((2,2,2)) 

setNempty(nempty)¶

Sets the number of empty bands.

Parameters: nempty (int) – number of empty bands
Example

>>> gs.setNempty(10) 

setNonCollinearSpin(lspinorb=False)¶

Sets non collinear spin. Requires fully relativistic pseudopotentials. Valid only for QuantumEspresso calculations.

Optionally spin-orbit can be turned on.

Parameters: lspinorb (boolean) – spin-orbit, optional
Example

>>> gs.setNonCollinearSpin() 

updateSpecies(symbol, url)¶

Update a species.

Parameters

symbol (string) – chemical symbol
url (string) – url

Example

>>> geom.addSpecies( "Si", "http://www.quantum-simulation.org/potentials/sg15_oncv/upf/Si_ONCV_PBE-1.1.upf" ) 

Note

You can use this method to add either upf or xml pseudopotentials. However it is forbidded to mix them.

Data Container¶

class westpy.dataContainer.DataContainer¶

Bases: object

Class for representing an in-memory data container.

Example

>>> from westpy import * 
>>> dc = DataContainer()

checkKeys(printSummary=True)¶

Checks that all keys are described.

Parameters

printSummary (boolean) – if True prints summary
key (string) – key

Returns

True if all keys are described, False otherwise.

Return type

boolean

Example

>>> from westpy import *
>>> dc = DataContainer()
>>> dc.upsertPoint({"a":1, "b":2},{"energy":-4.5}) 
>>> dc.upsertKey("a","the first letter") 
>>> dc.upsertKey("b","another letter") 
>>> dc.upsertKey("energy","a quantity")
>>> dc.checkKeys() 

removeKey(key)¶

Removes the description of a key

Parameters: key (string) – key
Example

>>> from westpy import *
>>> dc = DataContainer()
>>> dc.upsertKey("a","the first letter") 
>>> dc.removeKey("a") 

removePoint(identifier)¶

Removes point with given identifier from the data container.

Parameters: identifier – identifier
Example

>>> from westpy import *
>>> dc = DataContainer()
>>> dc.upsertPoint({"a":1, "b":2},{"energy":-4.5}) 
>>> dc.removePoint({"a":1, "b":2}) 

showPoints()¶

Shows all points of the data container.

Example

>>> from westpy import *
>>> dc = DataContainer()
>>> dc.upsertPoint({"a":1, "b":2},{"energy":-4.5}) 
>>> dc.showPoints() 

upsertKey(key, description)¶

Updates or inserts a new key and its description.

Parameters

key (string) – key
description – description

Example

>>> from westpy import *
>>> dc = DataContainer()
>>> dc.upsertKey("a","the first letter") 

upsertPoint(identifier, document, incremental_update=True)¶

Update or inserts an entry to the data container.

If identifier exists, update the document associated to the identifier, otherwise insert the document with the identifier.

Parameters

identifier – identifier
document – document
incremental_update (boolean) – if the document exists, only update it, do not remove its other keys.

Example

>>> from westpy import *
>>> dc = DataContainer()
>>> dc.upsertPoint({"a":1, "b":2},{"energy":-4.5}) 

Electronic Structure¶

class westpy.electronicStructure.ElectronicStructure¶

Bases: object

Class for representing an electronic structure calculation.

Example

>>> from westpy import * 
>>> es = ElectronicStructure()

addDataPoint(ksb, key, what)¶

Adds datapoint to data.

Parameters

ksb (3-dim int) – triplet of integers: k-point, spin, band (integer labels)
key (string) – key
what – content attached to key

Example

>>> from westpy import *
>>> es = ElectronicStructure()
>>> es.addKey("eks","Kohn-Sham energy in eV")
>>> es.addDataPoint([1,1,1],"eks",-4.6789)

addKey(key, description)¶

Describes metadata key.

Parameters

key (string) – key
description – description

Example

>>> from westpy import *
>>> es = ElectronicStructure()
>>> es.addKey("eks","Kohn-Sham") 

plotDOS(k=1, s=1, energyKeys=['eks'], sigma=0.1, weight=1.0, energyRange=[- 20.0, 0.0, 0.01], fname='dos.png')¶

Plots desnity of states (DOS).

Parameters

k (int) – k-point integer label
s (int) – spin integer label
energyKeys (list of string (needs to match the available keys)) – energy keys
sigma (float .OR. list of string (needs to match the available keys)) – standard deviation of gaussian (eV), optional
weight (float .OR. list of string (needs to match the available keys)) – weight, optional
energyRange (3-dim float) – energy range = min, max, step (eV), optional
fname (string) – output file name

Example

>>> from westpy import *
>>> es = ElectronicStructure()
>>> es.addKey("eks","Kohn-Sham energy in eV")
>>> es.addDataPoint([1,1,1],"eks",-4.6789)
>>> es.plotDOS(k=1,s=1,energyKeys=["eks"],energyRange=[-5.,-3,0.01]) 

removeKey(key)¶

Removes key from metadata.

Parameters: key (string) – key
Example

>>> from westpy import *
>>> es = ElectronicStructure()
>>> es.addKey("eks","Kohn-Sham") 
>>> es.removeKey("eks") 

showKeys()¶

Shows keys in metadata.

Example

>>> from westpy import *
>>> es = ElectronicStructure()
>>> es.showKeys() 

Session¶

class westpy.session.Session(emailId)¶

Bases: object

Class for setting up a session, connected to a remove server via rest APIs.

Example

>>> from westpy import *
>>> session = Session("your.email@domain.edu")

getToken()¶

Returns the token of the session.

Example

>>> from westpy import *
>>> session = Session("your.email@domain.edu")
>>> token = session.getToken()
>>> print(token)

run(executable=None, inputFile=None, outputFile=None, downloadUrl=[], number_of_cores=2)¶

Runs the executable on the remote server.

Parameters

executable (string) – name of executable
inputFile (string) – name of input file
outputFile (string) – name of output file
downloadUrl (list of string) – URLs to be downloaded
number_of_cores (int) – number of cores

Example

>>> from westpy import *
>>> session = Session("your.email@domain.edu")
>>> session.run( "pw", "pw.in", "pw.out", ["http://www.quantum-simulation.org/potentials/sg15_oncv/upf/C_ONCV_PBE-1.0.upf"] , 2 )
>>> session.stop()

status()¶

Returns whether the session is active and time left.

Example

>>> from westpy import *
>>> session = Session("your.email@domain.edu")
>>> session.status()

stop()¶

Stops the session and clears the remote workspace.

Example

>>> from westpy import *
>>> session = Session("your.email@domain.edu")
>>> session.stop()