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
Joule

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 fjson 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("https://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("https://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 an 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

Parameters:: fname (string) – filename of cube file
Returns:: (data, metadata)
Return type:: (np.array, 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.

Parameters:

rfname (string) – filename of cube file of real part
ifname – optional, filename of cube file of imag part

Returns:

(data, metadata), where data is (real part + j*imag part)

Return type:

(np.array, dict)

westpy.utils.wfreq2df(fname='wfreq.json', dfKeys=['eks', 'eqpLin', 'eqpSec', 'sigmax', 'sigmac_eks', 'sigmac_eqpLin', 'sigmac_eqpSec', 'vxcl', 'vxcnl', 'hf'])¶

Loads the wfreq JSON output into a pandas dataframe.

Parameters:

fname (string) – filename of JSON output file
dfKeys (list of string) – energy keys to be added to dataframe

Returns:

(dataframe, data)

Return type:

(pd.DataFrame, dict)

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

Parameters:

data (list of float) – volumetric data consisting real values
meta (dict) –
dict containing metadata with following keys:
- atoms: list of atoms in the form (mass, [position])
- org: origin
- xvec,yvec,zvec: lattice vector basis
fname (string) – filename of cubefile (existing files overwritten)

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.

Parameters:

data (list of complex) – volumetric data consisting complex values
meta (dict) –
dict containing metadata with following keys:
- atoms: list of atoms in the form (mass, [position])
- org: origin
- xvec,yvec,zvec: lattice vector basis
rfname (string) – filename of cubefile containing real part
ifname (string) – optional, filename of cubefile containing imag part

Atom¶

class westpy.atom.Atom(cell=None, ase_atom=None, symbol=None, cry_coord=None, abs_coord=None, **kwargs)¶

Bases: object

Class for representing a single atom.

An atom can be initialized by and exported to an ASE Atom object.

All internal quantities below are in atomic unit.

Attributes:: cell(Cell): the cell where the atom lives. symbol(str): chemical symbol of the atom. abs_coord(float array): absolute coordinate. cry_coord(float array): crystal coordinate.

Extra attributes can be attached to an atom.

property cry_coord¶

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( symbol="Si", abs_coord=(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, abs_coord, units=1.0)¶

Adds a single atom.

Parameters:

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

Example:

>>> from westpy import *
>>> geom = Geometry()
>>> geom.addAtom( symbol="Si", abs_coord=(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( "https://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 frac_coord: fractional coordinates :type frac_coord: 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 forbidden to mix them.

downloadPseudopotentials()¶

Download Pseudopotentials.

Example:

>>> from westpy import *
>>> geom = Geometry()
>>> geom.addAtomsFromOnlineXYZ( "https://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( "https://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( "https://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( "https://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 forbidden 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(kk=[1], ss=[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:

kk (list of int) – list of k-points
ss (list of int) – list of spin channels (must be [1], [2], or [1,2])
energyKeys (list of string (needs to match the available keys)) – energy keys
sigma (float .OR. string (needs to match the available keys)) – standard deviation of gaussian (eV), optional
weight (float .OR. 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.addDataPoint([1,1,2],"eks",-4.3456)
>>> es.addDataPoint([1,2,1],"eks",-4.4567)
>>> es.addDataPoint([1,2,2],"eks",-4.0123)
>>> es.plotDOS(kk=[1],ss=[1,2],energyKeys=["eks"],energyRange=[-5.,-3,0.01])

plotLDOS(kk=[1], ss=[1], energyKeys=['eks'], sigma=0.1, weight=1.0, energyRange=[-20.0, 0.0, 0.01], wfcKey='wfcFile', fname='ldos.png')¶

Plots desnity of states (DOS).

Parameters:

kk (list of int) – list of k-points
ss (list of int) – list of spin channels
energyKeys (list of string (needs to match the available keys)) – energy keys
sigma (float .OR. string (needs to match the available keys)) – standard deviation of gaussian (eV), optional
weight (float .OR. string (needs to match the available keys)) – weight, optional
energyRange (3-dim float) – energy range = min, max, step (eV), optional
wfcKey (string (needs to match the available keys)) – wavefunction file
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.addDataPoint([1,1,2],"eks",-4.3456)
>>> es.addDataPoint([1,2,1],"eks",-4.4567)
>>> es.addDataPoint([1,2,2],"eks",-4.0123)
>>> es.plotLDOS(kk=[1],ss=[1,2],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()