Manual

The complete WESTpy reference is reported below.

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

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:
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.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.

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" ) 
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) ) 

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()